Websphere Portal Troubleshooting PDF
-
Upload
vasupandian -
Category
Documents
-
view
1.036 -
download
22
Transcript of Websphere Portal Troubleshooting PDF
Version 6.0
This edition applies toWebSphere Portal for z/OS Version 6.0.
A form for readers’ comments appears at the back of this publication. If the form has been removed, address your
comments to:
International Business Machines Corporation
Department R0JA
P.O. Box 12195
Research Triangle Park, North Carolina
27709-2195
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2000, 2006. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Chapter 1. Troubleshooting . . . . . . 1
Tools for troubleshooting and diagnostics . . . . . 1
IBM Support Assistant . . . . . . . . . . 1
Logging and tracing . . . . . . . . . . . 2
Search the product documentation for a solution . . 20
Troubleshooting WebSphere Portal installation . . 21
Troubleshooting the cluster . . . . . . . . 28
Troubleshooting databases . . . . . . . . 31
Troubleshooting security . . . . . . . . . 33
Troubleshooting Web servers . . . . . . . 41
Troubleshooting access to the portal . . . . . 41
Troubleshooting administration . . . . . . . 49
Troubleshooting the XML configuration interface 56
Troubleshooting business process integration . . 63
Troubleshooting Workflow for composite
applications . . . . . . . . . . . . . 66
Troubleshooting Lotus Domino and the Extended
Products . . . . . . . . . . . . . . 66
Troubleshooting Domino and Extended Products
Portlets . . . . . . . . . . . . . . . 71
Troubleshooting Document Manager . . . . . 90
Troubleshooting Personalization . . . . . . 137
Troubleshooting portal design . . . . . . . 141
Troubleshooting portlet development . . . . 144
Troubleshooting portlets . . . . . . . . . 145
Troubleshooting Web Clipping portlet . . . . 149
Contact support . . . . . . . . . . . . 151
General installation troubleshooting worksheet 152
General configuration troubleshooting
worksheet . . . . . . . . . . . . . 153
General customization troubleshooting
worksheet . . . . . . . . . . . . . 154
General runtime troubleshooting worksheet . . 156
General programming troubleshooting
worksheet . . . . . . . . . . . . . 157
Chapter 2. Additional resources . . . 161
Resources for learning . . . . . . . . . . 161
Additional resources . . . . . . . . . . 161
Additional resources for planning . . . . . 162
Additional resources for installation . . . . . 165
Additional resources for administration . . . 165
Additional resources for development . . . . 166
Directory structure . . . . . . . . . . . 171
Chapter 3. Directory structure . . . . 175
Chapter 4. Notices and trademarks 179
© Copyright IBM Corp. 2000, 2006 iii
Chapter 1. Troubleshooting
Welcome to the IBM® WebSphere® Portal Enable for z/OS® Troubleshooting guide.
This guide is intended to help you solve problems without having to call IBM
support. If you do have to call IBM support, this guide provides the information
that you need to help your IBM service representative diagnose and resolve the
problem.
Can you re-create the problem?
Yes. If you can re-create the problem, you might want to enable tracing and then
re-create the problem to capture more log information. You can enable logging and
tracing for software that is shipped with WebSphere Portal. Enabling tracing makes
log output more verbose. For example, you can enable tracing within IBM
WebSphere Application Server to obtain information about application servers and
other processes. Because WebSphere Portal runs as an application server within
WebSphere Application Server, you can enable tracing to help pinpoint problems
that are related to the portal application server. Refer to “Logging and tracing” on
page 2 and the Message Catalog for more information. After tracing is enabled
continue to the next section, Researching a problem section.
No. If you cannot re-create the problem continue to the Researching a problem
section.
Researching a problem
Tools for troubleshooting and diagnostics
There are a number of tools and resources available to help you troubleshoot
issues and resolve problems with this product. Some of those are described here.
Since IBM WebSphere Portal Enable for z/OS runs with the IBM WebSphere
Application Server, additional troubleshooting tools and techniques are described
in the WebSphere Application Server documentation. These tools are intended to
assist you in understanding how to best operate your solution, and how you might
solve problems you and your users may encounter along the way. Should you
require further assistance to resolve these issues, the tools described here will help
you to identify and collect information which will be helpful when you do report
these issues to IBM Support.
IBM Support Assistant
IBM Support Assistant (ISA) provides quick access to product, education, and
support resources that can help you answer questions and resolve problems with
IBM software products on your own, without needing to contact IBM Support.
Different product-specific plug-ins let you customize IBM Support Assistant for the
particular products you have installed. IBM Support Assistant can also collect
system data, log files, and other information to help IBM Support determine the
cause of a particular problem.
You can use IBM Support Assistant (ISA) to help you in the following ways:
v To search through IBM and non-IBM knowledge and information sources across
multiple IBM products to answer a question or solve a problem
© Copyright IBM Corp. 2000, 2006 1
v To find additional information through product-specific Web resources; including
product and support home pages, customer news groups and forums, skills and
training resources and information about troubleshooting and commonly asked
questions
v To extend your ability to diagnose product-specific problems with targeted
diagnostic tools available via the Support Assistant
v To simplify collection of diagnostic data to help you and IBM resolve your
problems (collecting either general or product/symptom-specific data)
v To help in reporting of problem incidents to IBM Support through a customized
on-line interface, including the ability to attach the diagnostic data referenced
above or any other information to new or existing incidents
Finally, you can use the built-in Updater facility to obtain support for additional
software products and capabilities as they become available.
For more information, and to download and start using the IBM Support Assistant,
go to: Self-Help Central for WebSphere Portal
Logging and tracing
If you are experiencing a problem, you might want to enable tracing and then
recreate the problem to capture more log information. You can enable logging and
tracing for software that is shipped with WebSphere Portal. Enabling tracing makes
log output more verbose. For example, you can enable tracing within WebSphere
Application Server to obtain information about application servers and other
processes.
Links to important WebSphere Portal tracing questions
How do I turn on WebSphere Portal trace logging?
See “Trace logging” on page 9 for information.
What are the different trace settings and where are the logged?
See “WebSphere Portal run-time log file” on page 4 for information.
How do change the location of my logs?
See “Changing the log file name and location” on page 10
WebSphere Portal logs
This section contains information that assists an administrator in identifying and
correcting problems with WebSphere Portal.
v “Using WebSphere Portal log files”
– “Installation log files”
– “Migration log files” on page 3
Using WebSphere Portal log files
WebSphere Portal has log files that are created during installation and run time.
This section describes the content of the log files and recommendations for when
to check the log files.
Installation log files
The WebSphere Portal installation log files are in the following directory:
v z/OS: portal_server_root/log
2 Troubleshooting guide
The table lists each file, describes the file content and recommends when to check
the file for information that might assist in troubleshooting installation problems.
Log file name Description Problem symptoms
cmInit.log, jcrdb2zos.log,
yourLocationName.log
Contain trace information
generated during JCR (that
is, the DB2 Content Manager
Runtime Edition)
configuration.
v jcrdb2zos.log is generated
when the JCR database is
created in DB2 for z/OS
during database transfer.
v cmInit.log is generated
when the initial Document
Manager/Personalization
nodes are seeded into the
JCR database.
v yourLocationName.log is
generated when JCR data
is transferred from
Cloudscape to DB2 for
z/OS. (The file name will
match the target location
name.)
Check these logs if there are
problems during JCR
configuration.
ConfigMessages.log Contains messages that are
generated during installation.
The messages in this file are
translated for the language
that is specified during
installation.
Check this log for errors
generated during installation.
ConfigTrace.log Contains trace information
generated by WebSphere
Portal installation.
Check this log for errors
generated during installation.
DatabaseTransfer.log.n Contains trace information
generated during database
transfer.
Check this log if there are
problems during database
transfer.
Job logs of installation jobs
(such as EJPSCFG1,
EJPSBCA, and so on).
Contain trace information
generated during the
execution of the installation
jobs.
Check these files if there are
problems with a specific
installation step.
z/OS Console log Contains system output
during installation and
runtime.
Check this log if there are
access problems during
installation or errors in
system software.
Note: Additionally, you can check the WebSphere Application Server log files
located in the was_profile_root/logs directory if there are errors during
installation, especially the file wsadmin.traceout.
Migration log files
The migration log files are in the following directory:
v z/OS: portal_server_root/log
Chapter 1. Troubleshooting 3
The table lists each file, describes the file content, and recommends when to check
the file for information that might assist in troubleshooting installation problems.
Log file name Description Problem symptoms
MigrationTrace.log Contains trace information
that is generated by the
migration process.
Check this log if migration
stops before successful
completion.
MigrationMessages.log Contains messages that are
generated during migration.
The messages in this file are
translated for the language
that is specified during
installation.
Check this log for errors
generated during migration.
en.runningNumber.log,
trace.runningNumber.log
Contains trace messages of
the Web Content
Management migration tasks.
These files are located in the
directory:
portal_server_root/wcm/migration/log.
Check this log for errors
generated during migration.
Related information
v Chapter 1, “Troubleshooting,” on page 1
WebSphere Portal run-time logs
Using WebSphere Portal log files
IBM WebSphere Portal Enable for z/OS has log files that are created during run
time. This section describes the content of the log files and recommendations for
when to check the log files.
The run-time log files are:
v “WebSphere Portal run-time log file”
WebSphere Portal run-time log file
The WebSphere Portal log file contains messages and trace information, if tracing is
enabled. The default run-time log file is:
v z/OS: portal_server_root/log/trace.log
The WebSphere Portal log file contains messages and trace information, if tracing is
enabled. The default run-time log file is at the output location you specified as
ras_trace_outputLocation in your IBM WebSphere Application Server for z/OS
installation. It can either be in the job log of the servant region, in a CTRACE data
set, or in a file in HFS. For details, see Trace control settings in the information
center of WebSphere Application Server for z/OS.
Messages and trace information are contained in the same log file. Refer to the
topic “System event logging” on page 8 for details on how to configure logging
and for information on the grammar of the ″trace string″ configuration key.
The following table describes trace loggers for particular situations and problem
symptoms. Enabling the trace loggers can slow down WebSphere Portal.
4 Troubleshooting guide
Note: The trace strings beginning with com.ibm.wps.* are extensions in the IBM
portlet API.
Area of concern When to use Trace string Additional comments
Access Control Enable this tracer if you
want permissions for
resources to be explained in
detail, need to verify the
correctness of a permission,
or need to isolate a defect
in access control.
com.ibm.wps.ac.*=all The traces are easier to
evaluate while WebSphere
Portal usage is low.
Important: Enabling this
logger creates very large
log files.
Authentication com.ibm.wps.engine.*=all:
com.ibm.wps.services.puma.*=all:
com.ibm.wps.puma.*=all:
com.ibm.wps.sso.*=all:
com.ibm.wps.services.authentication.*=all
Command Use to turn on all
command trace loggers.
com.ibm.wps.commands.*=all
Composition Model Enable these messages if
you want to get more
information on how pages
are constructed, need to
verify page lists displayed
on WebSphere Portal for
correctness, or need to
isolate an error in the
WebSphere Portal
aggregation component.
com.ibm.wps.model.*=all:
com.ibm.wps.composition.*=all
The traces are easier to
evaluate while WebSphere
Portal usage is low.
Important: Enabling this
logger creates very large
log files.
Credential Vault com.ibm.wps.sso.credentialvault.*=all:
com.ibm.wps.command.credentialvault.*=all:
com.ibm.wps.portletservice.credentialvault.*=all:
com.ibm.wps.services.credentialvault.*=all:
com.ibm.portal.portlet.service.credentialvault.*=all
Database Deals with generated SQL
statements and the internal
flow in the WebSphere
Portal database layer.
com.ibm.wps.datastore.*=all:
com.ibm.wps.services.datastore.*=all
Important: Enabling this
logger will create very large
log files.
Engine Use to enable all engine
trace loggers.
com.ibm.wps.engine.*=all
General com.ibm.wps.*=all
Note: If you want to use
general tracing but do not
want render times to be
displayed for such portlets,
you must selectively
disable tracing using the
following trace string:
com.ibm.wps.pe.PortletRenderTimeLoggingHelper=info
When general tracing is
enabled and parallel portlet
rendering is turned on,
portlets that are configured
to be rendered in parallel
will display the render time
as part of the portlet
content.
Mail Service Use to diagnose problems
with the Mail Service.
com.ibm.wps.services.mail.*=all
Mapping URLs Use to diagnose problems
with the user-defined
mappings of URLs
com.ibm.wps.mappingurl.*=all:
com.ibm.wps.command.mappingurl.*=all
Chapter 1. Troubleshooting 5
Area of concern When to use Trace string Additional comments
Personalization com.ibm.websphere.personalization.*=all
com.ibm.dm.pzn.ui.*=all
When Personalization is
installed outside of a
WebSphere Portal server,
Personalization will log
using WebSphere
Application Server tracing
with the same trace strings.
Document Manager com.ibm.wps.pdm.*=all=enabled
com.ibm.content.*=all=enabled
com.ibm.icm.*=all=enabled
WebSphere Portal Search Use to turn on all
WebSphere Portal Search
messages.
com.ibm.portal.search=all For detailed information
refer to Logging and
tracing in Portal Search.
Enable to obtain messages
about URLs that are
discovered by the crawler
but could not be fetched
and indexed for different
reasons.
com.ibm.portal.search.notIndexed=all
Enable to obtain messages
about the crawling process.
com.ibm.portal.search.crawler=all
Enable to obtain messages
about failures that happen
during a crawl.
com.ibm.portal.search.crawler.failure=all
Enable to obtain messages
about the indexing process.
com.ibm.portal.search.index=all
Enable to obtain messages
about failures that happen
during the indexing
process.
com.ibm.portal.search.index.failure=all
Portlet Container com.ibm.wps.pe.pc.*=all:
org.apache.jetspeed.portlet.Portlet=all
javax.portlet.Portlet=all
Portlet Environment com.ibm.wps.pe.ext.*=all:
com.ibm.wps.pe.factory.*=all:
com.ibm.wps.pe.om.*=all:
com.ibm.wps.pe.util.*=all
Deployment com.ibm.wps.pe.mgr.*=all:
com.ibm.wps.services.deployment.*=all:
com.ibm.wps.command.applications.*=all:
com.ibm.wps.command.portlets.*=all
Portlets Use to diagnose problems
with portlets.
com.ibm.wps.portlets.*=all:
org.apache.jetspeed.portlet.PortletLog=all
Enables tracing for all
portlets. Therefore, place
the suspect portlet on a
separate page for testing.
Scripting Interface Use this trace string to
diagnose problems with the
Portal Scripting Interface,
or with application
interface scripting, and the
execution of such scripts.
com.ibm.wps.scripting.*=all: The traces are easier to
evaluate while WebSphere
Portal usage is low.
Note: Enabling this logger
can create large log files
fast.
6 Troubleshooting guide
Area of concern When to use Trace string Additional comments
Selfcare Use to diagnose problems
with user registration and
profile editing.
com.ibm.wps.services.puma.*=all:
com.ibm.wps.puma.*=all
Use this logger if there are
errors in the sign-up, Edit
My Profile, and the Manage
Users and Groups portlets.
Services: EventBroker com.ibm.wps.services.registry.EventHandlerRegistry=all:
com.ibm.wps.services.events.*=all
Services: Finder Use for debugging the
resolution of file names.
com.ibm.wps.services.finder.*=all
Services: Loader Use to trace the dynamic
class loading performed by
this service.
com.ibm.wps.services.ServiceManager=all
ServicesNaming Use to debug the lookup of
objects by the naming
service.
com.ibm.wps.services.naming.*=all
ServicesNavigator Use to diagnose problems
with parts of page
aggregation and display.
com.ibm.wps.services.navigator.*=all
ServicesRegistry Use to view the policies of
the internal portlet object
caching and watch it reload
its content.
com.ibm.wps.services.registry.*=all
Services Use for switching on
tracing for all services.
com.ibm.wps.services.*=all
SSO Use to turn on all SSO
tracer loggers listed after
this trace logger.
com.ibm.wps.sso.*=all Use this logger if errors
occur when use the
Security Vault task on the
Security page of the
Administration pages.
WSRP administration Use to diagnose problems
occurring during the
administration of Web
Services for Remote Portlets
(WSRP) with WebSphere
Portal.
com.ibm.wps.command.wsrp.*=all:
com.ibm.wps.wsrp.cmd.*=all
WSRP Consumer Use to diagnose problems
occurring during the use of
WSRP with WebSphere
Portal as a Consumer.
com.ibm.wps.wsrp.consumer.*=all
WSRP Producer Use to diagnose problems
occurring during the use of
WSRP with WebSphere
Portal as a Producer.
com.ibm.wps.wsrp.producer.*=all
XML configuration interface Use to diagnose problems
with the XML
import/export of
WebSphere Portal
configurations.
com.ibm.wps.command.xml.*=all
Related information
v Chapter 1, “Troubleshooting,” on page 1
Chapter 1. Troubleshooting 7
WebSphere Application Server tracing and log files
IBM WebSphere Application Server for z/OS has log files and a tracing function.
Some of the WebSphere Application Server for z/OS log files are located in the
directory was_profile_root/logs. Furthermore, if you enable WebSphere
Application Server for z/OS tracing, depending on option
ras_trace_outputLocation, the job logs or log streams of the application server
control and servant region contain information that might be helpful in detecting
and diagnosing problems. Check the information center of WebSphere Application
Server for z/OS for details on how to enable tracing and logging. For information,
see Trace controls for IBM service.
Related information
v Chapter 1, “Troubleshooting,” on page 1
Member Manager tracing files
Using Member Manager tracing
Member Manager uses the WebSphere Application Server trace facilities to create
trace information. If you need detailed trace output of Member Manager to debug
a problem, follow these steps:
1. Ensure that WebSphere Portal is started.
2. Open the Administrative Console.
3. Go to section Troubleshooting → Logs and Traces → WebSphere_Portal →
Diagnostic Trace.
4. Make sure that the check box Enable Log is selected.
5. Under the Additional Properties section, click on Change Log Detail Levels.
Enter the following information in the text box:
com.ibm.websphere.wmm.*=all:com.ibm.ws.wmm.*=all:WSMM=all
6. Click OK and save the changes to the master configuration.
7. Restart WebSphere Portal.
The resulting traces of Member Manager will be written to the output location you
specified as ras_trace_outputLocation in the WebSphere Application Server for
z/OS administration console. Check theinformation center of WebSphere
Application Server for z/OS for details on what can be specified. For more
information, refer to Setting trace controls.
Related information
v Chapter 1, “Troubleshooting,” on page 1
System event logging
The system event logging facility of IBM WebSphere Portal Enable for z/OS
enables the recording of information about the operation of WebSphere Portal.
Event logs provide administrators with information on important or abnormal
events, especially errors that occur during the operation of the product. In
addition, event logs gather debugging information that helps IBM support to
resolve problems.
WebSphere Portal provides two types of logging: logging of messages and logging
of debugging messages called traces.
For information about how to use log files and a list of trace logger strings refer to
“WebSphere Portal logs” on page 2.
8 Troubleshooting guide
This topic has the following sections:
v “Message logging”
v “Trace logging”
v “Using separate log files” on page 10
v “Changing the log file name and location” on page 10
v “Changing the language used in the log file” on page 11
v “Reference: Log file format” on page 11
Message logging
WebSphere Portal provides the logging of messages that report errors and status
information.
The following types of messages are provided:
Informational
A condition worth noting but does not require the user to perform an
action.
Warning
An abnormal condition has been detected. The user may have to take
action. However, WebSphere Portal code is able to handle the condition
without failing.
Error A serious failure in the execution of the application that requires further
action.
Trace logging
WebSphere Portal provides the logging of debugging messages called traces. These
traces are useful for fixing problems. However, to save system resources, they are
switched off by default.
Traces can be set for different durations:
Temporary
Traces can be set for a temporary period by using the administration
portlet Enable Tracing or the IBM WebSphere Application Server
administrative console. To set traces by using the portlet, proceed by the
following steps:
1. Log in as the administrator.
2. From the Main Menu click Administration → Portal Analysis → Enable
Tracing. The Enable Tracing portlet appears.
3. Type the required trace string into the field Append these trace
settings:. For example, this can be
com.ibm.wps.command.credentialvault.*=finest
4. Click the Add icon. Enable Tracing updates the field Current trace
settings:
Note: Restarting WebSphere Portal will remove traces that were set by
using the Enable Tracing Administration portlet.To disable tracing, do either of the following:
v Select the current trace settings under Current trace settings: and click
the Remove icon. By the example given above, the current setting can be
com.ibm.wps.command.credentialvault.*=finest.
Chapter 1. Troubleshooting 9
v Type the trace string *=info into the field Append these trace settings:
and click the Add icon. This trace string overwrites all settings listed
under Current trace settings: and resets it to the default.
Extended
To enable trace settings for a longer period of time, that is, for more than
one session, switch them on in the WebSphere Application Server
configuration. Proceed by the following steps:
1. Access the WebSphere Application Server Administrative Console by
using this URL: http://hostname:port_number/ibm/console
2. Go to the Server → Application servers section.
3. Select the application server.
4. Click Troubleshooting → Change Log Detail Levels.
5. Specify the required trace settings. For example, this can be
com.ibm.wps.command.credentialvault.*=finest
6. Save your updates.
7. Restart WebSphere Portal.
8. To disable tracing, specify tracestring: *=info and restart WebSphere
Portal.
Using separate log files
By default, WebSphere Portal logs and traces are written to the output location
configured for the servant region. Depending on the value you specified as
ras_trace_outputLocation in the WebSphere Application Server administrative
console, this can be the job log of the servant region, or a CTRACE data set, or a
file in HFS. For details, see Trace control settings. However, WebSphere Portal
supports the redirection of its trace and message logging into separate log files.
This can help you separate the log output of components from the output of other
applications and WebSphere Application Server itself. The redirection is disabled
by default. If you enable it, WebSphere Portal creates its own log file. It writes all
trace and message logs to this new log file and no longer to the output location of
WebSphere Application Server. You enable the redirection into separate log files by
setting the log configuration key useAppServerLog to false in the file
log.properties. This file is located in the following directory location:
v z/OS: portal_server_root/shared/app/config
Changing the log file name and location
When you configure WebSphere Portal to write its trace and message logging to a
separate log file, a new file named trace.log is created. This file is updated when
an error occurs or if trace logs are created. The file is created in the following
directory:
v z/OS: portal_server_root/log
You can change the location and the name of this file by changing the
configuration key logFileName in the log configuration file log.properties. The file
is located in the following WebSphere Portal directory:
v z/OS: portal_server_root/shared/app/config
The specified log file name can contain one of two tokens that are automatically
replaced with the corresponding values when starting WebSphere Portal:
10 Troubleshooting guide
v $APPSERVER_NAME: The name of the application server. Use this token for vertical
clusters to enforce that the different application servers write into different files
or directories if they share the same file system.
v $CREATE_TIME: The date and time at which the file was created.
You can specify the location of the log file either using a relative path or an
absolute path.
v A value such as logfilename=log/$APPSERVER_NAME/Portal_$CREATE_TIME.log
causes the log file to be created in a directory that is relative to theWebSphere
Portal installation directory. In this case, on a server that is named PORTAL1, the
log file would be created in the following WebSphere Portal directory:
– z/OS: portal_server_root/log/PORTAL1/Portal_2003.05.16-13.36.14.log
v A value such as logfilename=/temp/wps_$CREATE_TIME.log causes the log file to
be created in the absolute location specified.
If you change the location of the log file, you must restart WebSphere Portal in
order to use the new location.
Changing the language used in the log file
By default, information in the log file is written in the language that was used for
the WebSphere Portal installation. However, because WebSphere Portal supports a
number of languages, you can choose to have the log file information written in a
language other than that used during installation.
To change the language used for the log file, edit the file log.properties. This file
is located in the following WebSphere Portal directory:
v z/OS: portal_server_root/shared/app/config
Add the following line:
locale=xx
where xxis the two-letter abbreviation for the locale. For a list of the locale
abbreviations used with WebSphere Portal, refer to Directories for languages. For
example, to have log information generated in English, you would add the
following line:
locale=en
Reference: Log file format
If the logs are written to the log file of WebSphere Portal and not redirected to the
logging facility WebSphere Application Server, the log file consists of a sequence
log records that are separated by blank lines.
The log records have the following format:
timestamp classification classname method threadID
messagecode: logmessage
Where:
v timestamp is the time (to the millisecond) when the log record was created.
v classification is one of the following letters:
– E for error messages
– W for warning messages
Chapter 1. Troubleshooting 11
– I for informational messages
– l for traces (low details)
– m for traces (medium details)
– h for traces (high details)v classname is the Java class containing the code that triggered the log event.
v method is the name of the Java method containing the code that triggered the log
event.
v messagecode is a unique identifier for this message, to uniquely identify the
specific message and refer to it when consulting documentation or support. The
message code is only available for error, warning, or informational messages,
and not for traces. It consists of:
– a four-character identifier for the component that defines the message.
– a four-digit number identifying the message in the component.
– a one-letter classification code, which can be E, W or I , as defined above.v logmessage is the actual log message describing the logged event. Error,
warning, and informational messages are translated into the system locale. Trace
messages are not translated.
v threadID is the identification of the thread that triggered the log event.
Note:
1. Traces are written only if the specific tracing facility is enabled; all other
messages are written unconditionally.
2. The system locale is part of the general internationalization features of
WebSphere Portal and can be configured via LocalizerService. For more
information see the information center topic Portal configurationPortal
configuration.
The following is an example of a log record:
2003.05.16 13:36:14.449 W com.ibm.wps.services.datastore.DataStoreServiceImpl init 0000003a
DSTO0063W: The transaction isolation level is not set to READ_COMMITTED.
The current value is TRANSACTION_REPEATABLE_READ.
Related information
v Portal configuration
v Administering
v “WebSphere Portal logs” on page 2
v Designing
v Chapter 1, “Troubleshooting,” on page 1
v “Directory structure” on page 168
Transcoding Technology logging and tracing
Transcoding Technology sends events to the message and trace logs. Message
logging records informational messages about normal operations as well as
warnings and error messages. Tracing provides more detailed information for
troubleshooting problems. Messages are translated into the language specified for
your machine. Trace records are not translated. By default, message logging is
turned on and tracing is turned off. You can turn tracing on and off by selecting
the TranscodingTraceLogger component in the Enable Tracing page in the
Administration Portal.
12 Troubleshooting guide
To enable tracing, follow these steps:
1. Download the following files into portal_server_root/IBMTrans/etc/ras:
TranscoderRASTraceLogger.properties
TranscoderTraceMaskFilter.properties
2. Restart IBM WebSphere Portal Enable for z/OS.
Message logging
Message categories
Three categories of messages are written to the message log file:
v Information: records normal events. Use these messages to determine whether
expected operations occur, for example, to verify that a configuration change
takes place as expected.
v Warning: indicates a possible problem. Requests might still be handled
successfully.
v Error: indicates a definite problem requiring administrator attention. Requests
will probably not be handled successfully.
Message files
Message files are created in the portal_server_root/IBMTrans/log directory. The
first message file created is named TranscoderMessages1.log. When the maximum
size is reached, this file will be renamed to TranscoderMessages.log and a new
TranscoderMessages1.log file is created for new messages. The default message file
size is 512 kilobytes. See the WebSphere Portal documentation for information
regarding changing the file size. TranscoderMessages1.log is always the newest
file.
Viewing messages
You can view the messages in the active log file, TranscoderMessages1.log. You
can also open the other message files with your favorite ASCII editor.
Tracing
Tracing records the specific behavior of Transcoding Technology, recording
information useful in the diagnosis of problems.
Trace files
Trace files are created in the portal_server_root/IBMTrans/log directory. The first
trace file created is named TranscoderTrace1.log. When the maximum size is
reached, this file will be renamed to TranscoderTrace2.log and a new
TranscoderTrace1.log file created for new messages. The default trace file size is
512 kilobytes. See the WebSphere Portal documentation for information regarding
changing the file size. TranscoderTrace1.log is always the newest file.
When the maximum number of trace files has been filled, the oldest file will be
deleted, the suffix number of each remaining file will be increased by one, and a
new TranscoderTrace1.log will be created for new messages. A new file is begun
when Transcoding Technology is restarted. The default number of trace files is 3.
See the WebSphere Portal documentation for information regarding changing the
maximum number of trace files.
Chapter 1. Troubleshooting 13
Enabling Request Viewer for Transcoding Technology
The Request Viewer for Transcoding Technology is disabled by default. The
following messages in the portal application server trace related to the Request
Viewer should be ignored if you are not using the transcoding request viewer
monitor.
IPX1041 The plugin named com.ibm.wbi.viewer.ViewerServerPlugin could not be
initialized. TPX1084E Underlying error detail:
com.ibm.wbi.PluginException: RMI is disabled.
Note: The Request Viewer is not supported in WebSphere Portal for z/OS.
Gathering troubleshooting data
If you have a problem while running Transcoding Technology, there is a certain set
of information that will be useful in troubleshooting. The RASCollect program will
package the necessary files and settings to make it easy to gather diagnostic
information. If you need to use this function, execute the following command:
v z/OS: RASCollect.sh
This is located at portal_server_root/IBMTrans.
This will create a RASCollect.zip or RASCollect.tar file that you can send to your
service representative.
Web Content Management tracing files
IBM Workplace Web Content Management™ uses the IBM WebSphere Application
Server trace facilities to create trace information. If you need detailed trace output
of Web Content Management to debug a problem, follow these steps:
1. To permanently enable tracing, do the following:
a. Start WebSphere Application Server.
b. Open the Administrative Console.
c. Go to section Troubleshooting>Logs and
Traces>WebSphere_Portal>Diagnostic Trace.
d. Make sure that the check box Enable Trace is selected.
e. Enter any of the following in the TraceSpecification field:
v com.ibm.workplace.wcm.*
v com.aptrix.*
v com.presence.*
For example, to trace all events, enter the following:
com.ibm.workplace.wcm.*=all:com.aptrix.*=all:com.presence.*=all
f. Save the changes.
g. Restart IBM WebSphere Portal Enable for z/OS.2. To enable tracing just for the current WebSphere Portal session, do the
following:
a. Go to Administration > WebSphere Portal > Portal Analysis > Enable
Tracing >
b. Enter any of the following in the Append these trace settings field:
v com.ibm.workplace.wcm.*
v com.aptrix.*
v com.presence.*
14 Troubleshooting guide
For example, to trace all events, enter the following:
com.ibm.workplace.wcm.*=all:com.aptrix.*=all:com.presence.*=all
Here is a list of advanced trace settings:
Trace setting: Description:
com.ibm.workplace.wcm.services.content.* This enables low level tracing for every item.
com.ibm.workplace.wcm.domain.transformers.control.controltype You can enable tracing for any of the
following control types:
v HistoryControlTransformer
v IdentityControlTransformer
v ProfileControlTransformer
v SecurityControlTransformer
v WorkflowControlTransformer
com.ibm.workplace.wcm.domain.transformers.control.* This enables the tracing for all control types
for all items.
Chapter 1. Troubleshooting 15
Trace setting: Description:
com.ibm.workplace.wcm.domain.transformers.controllable.controllabletype You can enable tracing for any of the
following controllable types:
v AbstractControllableTransformer
v AlternateDesignCmpntTransformer
v AlternateLinkCmpntTransformer
v ArrayCmpntTransformer
v AttributeReferenceCmpntTransformer
v BasePathCmpntTransformer
v BaseReferenceCmpntTransformer
v CategoryTransformer
v CmpntReferenceTransformer
v CmpntTransformer
v ConfigParamCmpntTransformer
v ContentLinkTransformer
v ContentSpotCmpntTransformer
v ContentTransformer
v ContextPathCmpntTransformer
v ControllableNodeValueTransformer
v ControllableTransformer
v DateCmpntTransformer
v EmailActionTransformer
v ExpireActionTransformer
v ExternalLinkTransformer
v FEDCmpntReferenceTransformer
v FEDCmpntTransformer
v FileResourceCmpntTransformer
v HistoryCmpntTransformer
v HTMLCmpntTransformer
v IDCmpntTransformer
v ImageResourceCmpntTransformer
v IndentCmpntTransformer
v IndexCmpntTransformer
v InlineEditCmpntTransformer
v InlineEditReferenceCmpntTransformer
v JSPCmpntTransformer
v LinkCmpntTransformer
v MenuCmpntTransformer
v NavigatorCmpntTransformer
v NoPrefixBasePathCmpntTransformer
v NoPrefixServletPathCmpntTransformer
v NumericCmpntTransformer
v ObjectSummaryTransformer
v OptionSelectionCmpntTransformer
v PageInfoCmpntTransformer
v PagingCmpntTransformer
v PDMCmpntReferenceTransformer
v PDMCmpntTransformer
v PlaceholderCmpntTransformer
v PlutoSubscriberTransformer
v PlutoSyndicatorTransformer
v PrefixPathCmpntTransformer
16 Troubleshooting guide
Trace setting: Description:
com.ibm.workplace.wcm.domain.transformers.controllable.* This enables the tracing for all controllable
types for all items.
The resulting traces of Web Content Management will be written to the output
location you specified as ras_trace_outputLocation in the WebSphere Application
Server for z/OS administration console. Check the information center of
WebSphere Application Server for z/OS for details on what can be specified. For
more information, refer to Setting trace controls.
Configuring WebSphere Portal for site analysis logging
IBM WebSphere Portal Enable for z/OS implements a logging function for your
usage data.
Note: If you want to generate reports for portlet actions, you must write a custom
report.
v Enable site analysis logging
v Disable site analysis logging
Enable site analysis logging
Site analysis logging is not enabled by default.
To configure WebSphere Portal for site analysis logging, set the following
parameters in the WP SiteAnalyzerLogService as described in Setting configuration
properties.
1. Set the parameters for the file names of the log files and backup log files. To
specify the file name format, follow these instructions and use the tokens listed
after the instructions:
a. Search for the parameter SiteAnalyzerFileHandler.fileName . Use this
parameter to determine the location and filename of the log file. The default
value is log/sa.log .
b. Search for the parameter SiteAnalyzerFileHandler.backupFileName . Use
this parameter to determine the location and filename of the backup file for
the log file. The default value is log/sa_$CREATE_TIME.log .When the log file is backed up, the current data is stored in a file named by the
parameter SiteAnalyzerFileHandler.backupFileName you specified (default
log/sa_$CREATE_TIME.log ) and a new file is created for the new data with the
name you specified by the SiteAnalyzerFileHandler.fileName parameter
(default sa.log ).
When defining the names for the log files and backup files, you can specify the
three following tokens as part of the directory location or file name:
$APPSERVER_NAME
The name of the application server. Use this token for vertical clusters
to enforce that the different application servers write into different files
if they share the same file system.
$CREATE_TIME
The date and time at which the file was created. The date format of this
token is specified by the SiteAnalyzerFileHandler.dateFormat
parameter as described below.
Chapter 1. Troubleshooting 17
$CLOSE_TIME
The date and time at which the file was closed. The date format of this
token is specified by SiteAnalyzerFileHandler.dateFormat parameter
as described below. For a file that WebSphere Portal is currently writing
to, the value for $CLOSE_TIME is the same as $CREATE_TIME.An example with all three tokens: You can specify the file location and name
for a log file or backup file as follows: log/backup/$APPSERVER_NAME/sa_$CREATE_TIME_$CLOSE_TIME.log .
The format for the $CREATE_TIME and $CLOSE_TIME tokens is defined by the
value set for the SiteAnalyzerFileHandler.dateFormat parameter as described
in the next step below.
2. Set the parameter for the date format tokens in the log file names. To do this,
search for the parameter SiteAnalyzerFileHandler.dateFormat . Use this
parameter to set the date and time formats in the $CREATE_TIME and
$CLOSE_TIME tokens that are part of the log file names. The value you specify
determines the format of the date and time that replace the token in the names
of the base and backup log files. Example of date and time format:
SiteAnalyzerFileHandler.dateFormat=yyyy.MM.dd-HH.mm.ss .
3. To control the interval at which the log file is backed up, uncomment only one
of the following parameters and set the time interval for it:
v If you want to log in intervals of minutes, uncomment
SiteAnalyzerFileHandler.minutesPerLogFile and set the value to an integer
in the range 1 to 60.
v If you want to log in intervals of hours, uncomment
SiteAnalyzerFileHandler.hoursPerLogFile and set the value to an integer in
the range 1 to 24.
v If you want to log in intervals of days, uncomment
SiteAnalyzerFileHandler.daysPerLogFile and set the value to an integer that
indicates the number of days.Notes:
a. If you enable more than one date format interval, the smallest interval will
be used.
b. The difference between 60 minutes and 1 hour is as follows: If you specify
60 minutes the file is backed up after 60 minutes, but if you specify 1 hour,
the file is backed up on the next full hour interval, such as 01:00, 02:00 and
so on. For day intervals, the file is backed up only at 24:00 (midnight). If
you need more information about the date format, see the Javadoc for
java.text.SimpleDateFormat.The flexibility of the date format makes it easy to coordinate scheduling the file
backup. For example, you can configure WebSphere Portal to backup the site
analysis log every hour.
4. Activate selected loggers:
v To activate logging for certain loggers, uncomment the loggers that you want
to use and set them to true. See the following table for a description of each
logger.
WebSphere Portal Server Analysis Logger Description and Activity Logged
SiteAnalyzerSessionLogger.isLogging HTTP requests that include the URLs:/Command/Login/Command/Logout
18 Troubleshooting guide
WebSphere Portal Server Analysis Logger Description and Activity Logged
SiteAnalyzerUserManagementLogger.isLogging HTTP requests that include the URLs:/Command/UserManagement/CreateUser/Command/UserManagement/DeleteUser/Command/UserManagement/CreateGroup/Command/UserManagement/DeleteGroup
SiteAnalyzerPageLogger.isLogging HTTP requests that include the URLs:/Page/*/Command/Customizer/CreatePage/Command/Customizer/EditPage/Command/Customizer/DeletePage
SiteAnalyzerPortletLogger.isLogging HTTP requests that include the URLs:/Portlet/*
SiteAnalyzerPortletActionLogger.isLogging HTTP requests that include the URLs:/PortletAction/*
SiteAnalyzerErrorLogger.isLogging HTTP requests that include the URLs:/Error/Portlet/Error/PageThe referrer field points to a portlet name or a page
name. Examples of such referrer fields are:http://your.server.name/Portlet/1/PortletNamehttp://your.server.name/Page/1/PageName
SiteAnalyzerApplicationActionLogger.isLogging=true HTTP requests that include the URLs:/ApplicationAction/*
5. Restart the WebSphere Portal application server to commit the changes.
Disable site analysis logging
Site analysis logging can have performance impacts so you might want to disable
it when not in use. By default site analysis logging is not enabled. To disable site
analysis logging, search for the desired parameter(s) as listed in the table above
and set them to false.
Related information
v “Understanding the site analysis log”
Understanding the site analysis log:
The IBM WebSphere Portal Enable for z/OS site analysis log is:
/wp_root/log/sa_date_time.log
where wp_root is the WebSphere Portal root directory and date_time is the date and
time the file was created. The current (active) log file is named sa.log. As explained
in the previous section, the dateFormat parameter determines the interval at which
the file is created.
The site analysis log uses the NCSA Combined log format, which is a combination
of NCSA Common log format and three additional fields: the referrer field, the
user_agent field, and the cookie field. The following example displays a sample
entry in the site analysis log. The table describes each field of the log format:
Chapter 1. Troubleshooting 19
9.37.3.88 - customer2 [10/Apr/2002:21:33:16 +0000]
"GET /Portlet/146/Welcome_Portlet?PortletPID=146&PortletMode=View&PortletState=Normal
HTTP/1.1" 200 -1 "http://myserver.company.com/Page/110/Welcome"
"Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 4.0)"
"JSESSIONID=OXDFAPVR4SXYZOIHSLVGA2Y"
Field in the Example Log Field Name and Explanation
9.37.3.88 host The IP address of the HTTP client that
sent the request
- rcf931 The identifier used to identify the
client making the request. If the client
identifier is not known, the field is set to the
the hyphen character ( - ).
customer2 username The user ID for the client. If the
user ID is not known, the field is set to the
the hyphen character ( - ).
[10/APR/2002:21:33:16 +0000] date:time: timezone The date and time of
the HTTP request.
"GET /Portlet/146/Welcome_Portlet?
PortletMode=
View&PortletState= Normal HTTP/1.1"
request The HTTP method, the URL of the
requested resource and the version of HTTP
used by the client.
200 statuscode The HTTP status code for the
request.
-1 bytes The number of bytes of data
transferred from the client as part of the
request. A value of -1 means unknown.
"http://myserver.company.com/Page/110/Welcome"
referrer The URL that linked the client to
the Web site. For some requests, the referrer
might not be logged. In such cases, the field
is set to empty double quotes: ″″
"Mozilla/4.0 (compatible; MSIE 5.5;
Windows NT 4.0)"
user_agent The type of Web browser used
by the client.
"JSESSIONID=OXDFAPVR4SXYZOIHSLVGA2Y" cookies The name and value of a cookie that
was sent to the client browser. If multiple
cookies were sent, the list is delimited by the
semicolon character.
Search the product documentation for a solution
This section identifies many troubleshooting tips. Search through this section to
find solutions to many common problems.
When first researching a problem start with the product documentation. Product
documentation might be provided with the product or on the Web. Start by
completing the following steps.
1. Review the Release Notes for additional information.
2. Review the documentation in this section.
Note: WebSphere Portal includes multiple software products. Therefore, you
might also have to refer to troubleshooting information for other
products. See Products and components overview for links to
information for other products.
20 Troubleshooting guide
Troubleshooting WebSphere Portal installation
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Problem: No panel for installing WebSphere Business Integration support”
v “Problem: Change to make if IBM HTTP Server and WebSphere Application
Server plugin installed” on page 22
v “Problem: Receive EJPIC0034E: unexpected service exception message” on page
22
v “Information on WebSphere Portal Version information and History information”
on page 22
v “Problem: Java processes continue to run” on page 23
v “Problem: General steps to perform if the installation fails ” on page 23
v “Problem: Reinstall after a failed installation ” on page 23
v “Problem: Installation fails after uninstalling a previous copy of WebSphere
Portal ” on page 23
v “Problem: Installation fails due to insufficient disk space ” on page 24
v “Problem: Some portlets failed to deploy ” on page 24
v “Problem: Errors related to XADatasources prevent restarting WebSphere
Application Server” on page 25
v “Problem: WpsHostPort property value not updated during installation” on
page 25
v “Problem: During DB transfer from Cloudscape to DB2 on z/OS, Portal
installation may fail at the job CNTL(EJPSDBT) for the table with SQL errors
below” on page 25
v “Problem: Errors are written to joblog of the Server Servant Region of
WebSphere Portal for z/OS” on page 26
v “Problem: 04E abend with reason code 005E0013 during execution of portal
installation jobs” on page 26
v “Problem: The people picker for Document Manager does not work after
upgrading WebSphere Portal to version 6.0.1.1” on page 27
v Related to ReleaseBuilder
– “ReleaseBuilder ignores deletion of attributes” on page 27
– “Problem: Warning when transferring complete configuration” on page 28
Problem: No panel for installing WebSphere Business Integration
support
When upgrading WebSphere Portal using the Graphical User Interface, you do not
see a panel asking you if you want to “Select to install business process support.”
Solution: This panel only shows up on the operating systems that support
WebSphere Business Integration, such as
v AIX 5.2 ML 5
v AIX 5.3 ML 2
v HP-UX 11iv1
v Solaris 9
v Windows (all versions)
Chapter 1. Troubleshooting 21
HP-UX 11iv2, SUSE, and RedHat do not support WebSphere Business
Integration.
Problem: Change to make if IBM HTTP Server and WebSphere
Application Server plugin installed
If you install IBM HTTP Server (IHS) and the associated WebSphere Application
Server Plug-in from the disk labeled SO-2 and intend to enable SSL services using
the https transport, then you must perform the following manual steps after
installation.
Solution: As user root, change directory to {IHS_ROOT}/lib and create a symbolic
link from libgsk7ssl.so to /opt/ibm/gsk7_64/lib64/libgsk7ssl_64.so. For
example,
CD /opt/IBMIHS/lib
ln -s /opt/ibm/gsk7_64/lib64/libgsk7ssl_64.so libgsk7ssl.so
Problem: Receive EJPIC0034E: unexpected service exception
message
Installation on a mounted directory fails with a EJPIC0034E: unexpected service
exception error.
Solution: If you receive this message, run df-k to see if there are problems with
your file systems or you can validate using df-k before installing.
Information on WebSphere Portal Version information and
History information
WebSphere Portal Version information: The WebSphere Portal Version
information tool can be used to gather information about the WebSphere Portal
product. This information may be useful when contacting customer support by
providing a snapshot of your WebSphere Portal product specifics. The WebSphere
Portal Version information tool is located in the following directory:
v z/OS: portal_server_root/bin
The tool can be invoked using the following:
v z/OS: ./WPVersionInfo.sh
You can also generate a report in html format by executing the genVersionReport
tool
v z/OS: ./genVersionReport.sh
History information:
The History information tool can be used to gather installation history for the
WebSphere Portal product. The History information tool is located in the following
directory:
v z/OS: portal_server_root/bin
The History information tool can be invoked using the following:
v z/OS:: ./WPHistoryInfo.sh
You can also generate a report in HTML format by executing the genHistoryReport
tool:
22 Troubleshooting guide
v z/OS: ./genHistoryReport.sh
Problem: Java processes continue to run
When canceling installation during one of the installation steps, there may be some
extra Java processes left running in the background.
Solution: Stop any running Java processes before attempting another installation.
Problem: General steps to perform if the installation fails
Solution: If the WebSphere Portal installation fails, follow these steps:
1. Verify that WebSphere Application Server has been installed correctly.
Ensure that the correct WebSphere Application Server Fix Packs and
interim fixes are installed. See the WebSphere Portal information
center for details concerning that prerequisite.
2. Before you use the installation program to install WebSphere Portal
or any other component that requires WebSphere Application Server,
verify that you can start and stop WebSphere Application Server.
3. Change the time-out request for the Simple Object Access Protocol
(SOAP) client. The default, in seconds, is 180. Within the
was_profile_root/properties/ directory, edit the soap.client.props
file. Change the line to:
com.ibm.SOAP.requestTimeout=6000
Problem: Reinstall after a failed installation
Solution: If a product fails to install, do the following steps before you attempt to
install again:
1. If an uninstallation program is available, run it before reinstalling the
product. If the installation failed before the uninstallation program
was created or if the uninstallation program fails, manually delete
the installation directory and all of its contents before reinstalling the
product. See the uninstallation section for more information on
manual uninstallation.
2. Run the uninstallation before reinstalling the product. See the
uninstallation section for more information on uninstallation. If the
uninstallation jobs fail, manually uninstall the portal before
reinstalling the portal. For more information on manual
uninstallation, see the instructions in “Problem: Installation fails after
uninstalling a previous copy of WebSphere Portal .”
Problem: Installation fails after uninstalling a previous copy of
WebSphere Portal
If the WebSphere Portal installation fails after you have uninstalled a previous
copy of WebSphere Portal, ensure that no components of the WebSphere Portal
remain before you attempt to install WebSphere Portal again.
Solution:
1. Open the Administrative Console for WebSphere Application Server.
Verify that all of the WebSphere Portal components were removed by
the previous uninstallation. Manually remove any of the components
that remain. This includes the following elements:
Chapter 1. Troubleshooting 23
v Enterprise application: WebSphere Portal Enterprise Application
v Application server: WebSphere Portal
v Data sources: wpsdbDS and wmmDS
v JDBC driver: wpsdbJDBC2. On the portal machine, delete the WebSphere Portal directory
manually.
3. Restart the installation.
Problem: Installation fails due to insufficient disk space
Solution: If you receive a message during installation informing you that there is
insufficient disk space to install WebSphere Portal, you can complete the
following steps:
v Enlarge your WebSphere Portal configuration HFS so that it has a
primary extent of at least 1600 CYL. Ensure there are at least 1.5 GB
or 2300 CYL free space on the volume where the WebSphere Portal
configuration HFS is allocated.
v Ensure that your WebSphere Application Server configuration HFS is
at least as large, and has at least as much free space as the WebSphere
Portal configuration HFS.
v Make sure that you have enough space left in directories /tmp,
app_server_root/temp, and app_server_root/wstemp, preferably a few
hundred MB in each. If there is not enough space, stop all your
WebSphere servers using the stop command as documented, and tidy
up these directories.
Problem: Some portlets failed to deploy
If you encounter installation error EJPI0021W Some portlets failed to deploy, you
might be able to recover the installation. This error can be caused by some portlets
being left on WebSphere Application Server, or caused by WebSphere Portal not
running.
Solution: The user must first verify that WebSphere Portal starts and that the user
can log in as the WebSphere Portal administrator. If this cannot be
verified, something more severe than portlet deployment has gone
wrong and manually installing portlets will not work. If WebSphere
Portal login succeeds, you might be able to manually install portlets. To
manually install portlets, run the following commands:
1. Change directory to the WebSphere Portal configuration directory:
v z/OS: Open a command prompt, and change to the directory
portal_server_root/config.2. To drop all portlets, issue the following command:
v z/OS: portal_server_root/bin
xmlaccess -in portal_server_root/package/removeallportlets.xml -user portal_admin_id
-pwd portal_admin_password -url localhost:port_number/wps/config
Problem: WebSphere Portal configuration fails
If the configuration of WebSphere Portal fails with an error similar to the one
below, it might be that there is not enough swap space.
24 Troubleshooting guide
BUILD FAILED
file:../config/actions/was_cfg.xml:592: Execute failed: java.io.IOException: Not enough space
Total time: 44 minutes 10 seconds
Solution: Increase your swap space to a minimum of 2.5 GB. 3.0 GB is preferred.
Problem: Errors related to XADatasources prevent restarting
WebSphere Application Server
If WebSphere Application Server is stopped improperly or unexpectedly, you might
see errors similar to the one below when you try to restart:
J2CA0061W: Error creating XA Connection and Resource com.ibm.ws.exception.WsException:
DSRA8100E: Unable to get a XAConnection from the DataSource.
When this happens, you will be unable to restart WebSphere Application Server.
This is because there are XA transactions still pending in the translog directory.
Solution: Ask your system administrator to clear the transaction logs.
Problem: WpsHostPort property value not updated during
installation
If the wpconfig.properties file is locked during installation, such as when it is
open in a text editor, this can prevent the WpsHostPort property value from being
updated properly. This is unlikely to occur during most installation scenarios.
If the WpsHostPort property value is not set correctly, you will encounter problems
if you perform a task that refers to the wpconfig.properties file for the
WpsHostPort property, such using the xmlaccess command to deploy security
credentials or portlets. Because the command will attempt to use the default value
of 80 for WpsHostPort instead of the port number set at installation (which is what
the xmlaccess command expects), the command will fail.
Solution: Edit the wpconfig.properties file with a text editor, and change the
value of the WpsHostPort property to the value set during installation.
Problem: During DB transfer from Cloudscape to DB2 on z/OS,
Portal installation may fail at the job CNTL(EJPSDBT) for the table
with SQL errors below
[java] com.ibm.wps.config.db.transfer.TransferDatabase process main
[java] Adding DB Item 129 ICMADMIN."ICMSTJCRTSERRORS" (6)Columns to work queue.
[java] com.ibm.wps.config.db.transfer.TransferDatabaseTable createPreparedStatement main
[java] INSERT INTO WPADMIN.ICMSTJCRTSERRORS (TS,DOCID,WSID,PARENTID,ACT,MSG) VALUES( ?, ?, ?, ?, ?, ? )
[java] com.ibm.wps.config.db.transfer.TransferDatabaseTable transferDatabaseTable main
[java] Transferring table --{ ICMSTJCRTSERRORS }--
[java] com.ibm.db2.jcc.t2zos.y: [IBM/DB2][T2zos/1]T2zosPreparedStatement.readExecuteInternal:nativeExecute:4864:DB2 engine SQL
error, SQLCODE = -302, SQLSTATE = 22001, error tokens = 006;
Solution: After changing DDL, rerun the following jobs. It is strongly
recommended to change back to the original DDL for next
re-installation.
1. Change bupperpool BP0 to BP32K in TSERJRTS tablespace at
CNTL(EJPSCRDB)
CREATE TABLESPACE TSERJRTS IN JCRDBZOS USING STOGROUP JCRICMSG
PRIQTY 500 SECQTY 200 FREEPAGE 1 PCTFREE 5 LOCKSIZE ROW
LOCKMAX 0 CLOSE NO BUFFERPOOL BP32K CCSID UNICODE;
Chapter 1. Troubleshooting 25
2. Run CNTL(EJPSCRDB)
3. Run CNTL(EJPDBTV)
4. Change MSG column VARCHAR (3000) to 12000 in ICMSTJCRTSERRORS
table at:
installed PortalServer directory/V6R0M0/Portal/jcr/config/icmjcr.ddl
CREATE TABLE ICMSTJCRTSERRORS (
TS %CRT_TIMESTAMP%,
DOCID %CHAR%(26) %CODEPAGE%,
WSID INTEGER NOT NULL,
PARENTID %CHAR%(26) %CODEPAGE%,
ACT SMALLINT,
MSG %VARCHAR%(12000) %CODEPAGE%
)
5. Run CNTL(EJPSDBT)
Problem: Errors are written to joblog of the Server Servant
Region of WebSphere Portal for z/OS
During portal startup, error(s) similar to the following might be written to the
joblog of the Server Servant Region of WebSphere Portal for z/OS:
0000000a ArtifactLoade W com.ibm.ws.al.locator.TargetNamespaceSAXParser parseDocument(URL)
CWLAG0450W:unableto parse document
file:/opt/IBM/WebSphere/PortalServer/shared/app/oiexport/SearchML.xsd;
Reason: org.xml.sax.SAXParseException: The element type "complexType"
must be terminated by the matching
end-tag.
Solution: The error does not indicate a problem with WebSphere Portal nor with
XML conversion, and can be ignored.
Problem: 04E abend with reason code 005E0013 during
execution of portal installation jobs
During the execution of portal installation jobs, an 04E abend might occur.
Solution: Set the JOBCLASS(STC) so that it has the parameter SWA=ABOVE set.
This can be displayed using the ″$D JOBCLASS(STC)″ command, and
can be set dynamically with the ″$T JOBCLASS(STC),SWA=ABOVE″
command. It is recommended that you set this permanently in the JES2
parameters, but if it is not desirable for your installation, then set it
temporarily when running through the installation steps (both for
database transfer and enabling security).
Problem: Turkish language does not work with WebSphere Portal
install wizard
Using Turkish as the install wizard language when installing WebSphere Portal
causes errors.
Solution: When installing WebSphere Portal, use English as the install wizard
language regardless of operating system locale.
26 Troubleshooting guide
Problem: The people picker for Document Manager does not
work after upgrading WebSphere Portal to version 6.0.1.1
Some .war files such as wps.war and lwp_peoplePickerServlet.war lose their web
module map to the web server after upgrading WebSphere Portal. This may cause
problems when searching on people; for example, the Document Manager People
Picker will fail.
Solution: Perform the following steps to redeploy the .war file:
1. Navigate to Applications → Enterprise Applications.
2. Click on the name: for example LWP People.
3. Click on Map modules to servers.
4. Select the appropriate module; for example People Picker Servlet
lwp_peoplePickerServlet.war.
5. From the Clusters and Servers drop-down menu, select the web
server.
6. Click OK and save the configuration, and regenerate webserver
plugin.
Related to ReleaseBuilder
ReleaseBuilder ignores deletion of attributes
Problem: If you delete values of fields in the portal administrative user interface,
this might result in empty attributes in an XML export file. If you then use
ReleaseBuilder to extract the changes between the configurations before and after
the deletion of attributes, the difference file does not reflect the deletion of the
attributes.
Cause: This is a known limitation. The ReleaseBuilder does not recognize the
deletion of attributes. Refer also to “You cannot delete attributes by using the XML
configuration interface” on page 61.
Solution: After you have completed the staging process with ReleaseBuilder, delete
the attributes on the target portal system by using the same steps as you
performed on your source system.
Sample scenario and files: An example scenario and sample scripts are given in
the following.
1. You create configuration status export1 of your source portal by using the XML
configuration interface.
2. You modify your source portal by deleting the contents of fields in the portal
administrative user interface that lead to attributes without a value in an XML
export file.
3. You create configuration status export2 of your source portal by using the XML
configuration interface.
4. You use ReleaseBuilder to extract the changes between export1 and export2.
The resulting differential file does not contain the deleted attributes.
Sample XML script file snippet export1:
Chapter 1. Troubleshooting 27
<client action="update" domain="rel" manufacturer="dilbert" markup="html" markup-version="1.1"
name="puppy" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="250" version="1.0">
<useragent-pattern>dogert</useragent-pattern>
<client-capability update="set">dish</client-capability>
<client-capability update="set">html</client-capability>
</client>
Sample XML script file snippet export2:
<client action="update" domain="rel" manufacturer="dilbert" markup="html" markup-version="1.1"
name="" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="287" version="">
<useragent-pattern>dogert</useragent-pattern>
<client-capability update="set">dish</client-capability>
<client-capability update="set">html</client-capability>
</client>
From the two exports above, ReleaseBuilder generates the following differential
file:
<?xml version="1.0" encoding="UTF-8"?>
<!-- IBM WebSphere Portal/6.0 build wp600_154 exported on Wed Apr 05 14:24:19
EDT 2006 from xyz -->
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" build="wp600_154" type="update"
version="6.0.0.0" xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">
<portal action="locate">
<client action="update" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="287"/>
</portal>
</request>
If you use this ReleaseBuilder differential file to update your target portal, the
name and version attributes of the client tag are not deleted on the target portal.
To complete the update, you have to delete the attributes manually by using the
same steps by which you deleted the attributes on the source portal.
Problem: Warning when transferring complete configuration
When attempting to import the entire portal configuration, the transfer will be
successful with some warnings similar to, but not limited to, the following:
<status element="[virtual-resource 0_000000000000G3RCDT7BG0C100 uniquename=wps.USER_GROUPS
name=USER_GROUPS]" result="warning">
<message id="EJPXA0060W">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0060W: A user or group with ID cn=wpscontentadministrators,o=default
organization could not be retrieved from the portal datastore, possibly because it does
not exist. Related access-control configuration data will not be updated.
[virtual-resource 0_000000000000G3RCDT7BG0C100 uniquename=wps.USER_GROUPS name=USER_GROUPS]
</message>
</status>
<status element="[virtual-resource 0_000000000000G3RCDT7BG0G100 uniquename=wps.USERS name=USERS]"
result="warning">
<message id="EJPXA0060W">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0060W: A user or group with ID cn=wpscontentadministrators,o=default organization
could not be retrieved from the portal datastore, possibly because it does
not exist. Related access-control configuration data will not be updated.
[virtual-resource 0_000000000000G3RCDT7BG0G100 uniquename=wps.USERS name=USERS]
</message>
</status>
Solution: You can ignore these warnings or use the CleanupUsers.xml example file
to identify users and groups in your database who have been removed
from the user registry. Refer to Deregistering users and groups from
WebSphere Portal for more information.
Troubleshooting the cluster
If you experience a problem with the operation of IBM WebSphere Portal Enable
for z/OS, refer to the “Search the product documentation for a solution” on page
20
28 Troubleshooting guide
20 of the WebSphere Portal information center to determine whether it is a known
problem for which a workaround might exist. You can also review a list of
problems addressed by interim fixes and service packs at the Support site:
http://www.ibm.com/software/genservers/portalzos/support/. Be sure to also
look at Technotes section on the WebSphere Portal support site for any additional
known issues and workarounds which might have been identified after the initial
release.
WebSphere Portal uses and depends on the IBM WebSphere Application Server
infrastructure. Often an underlying issue in WebSphere Application Server can
affect WebSphere Portal, so it can be helpful to monitor the WebSphere Application
Server support site for known issues, fixes, and workarounds.
For information related to specific components, see the appropriate troubleshooting
topic:
v “WebSphere Portal does not start due to missing class file: com/ibm/wps/services/puma/AccessBean”
v “addNode command fails with ″doMergeConfig failed″ error”
v “Network error causes cluster install to fail” on page 30
v “Global settings cannot be set in a cluster by using the XML configuration
interface” on page 30
v “Cluster member startup does not complete due to ″Waiting for HAManager″
error” on page 30
WebSphere Portal does not start due to missing class file:
com/ibm/wps/services/puma/AccessBean
When attempting to access a WebSphere Portal cluster for the first time through an
external Web server, you might receive an Error 503 response. In addition, the
following messages are generated in the WebSphere Portal log file:
com.ibm.hrl.pse.portlets.WebScannerManager getSecretKeyFromCredentialVault
java.lang.NoClassDefFoundError: com/ibm/wps/services/puma/AccessBean
Solution: This problem can occur when the PortalAdminID property values
specified for each node do not match and you enabled security with an LDAP
registry. In this situation, the value of PortalAdminID is the fully-qualified
distinguished name (DN) of the WebSphere Portal administrator. Because the DN
is case sensitive, differences in case between PortalAdminID values on the various
nodes can cause a problem.
For example, the error can be generated if you have two nodes in the cluster with
the following values for PortalAdminId in the wpconfig.properties files:
v Node 1: uid=wpsadmin,ou=People,dc=raleigh,dc=ibm,dc=com
v Node 2: uid=wpsadmin,ou=people,dc=raleigh,dc=ibm,dc=com
To correct this problem, ensure that you have used the proper case for the value of
the PortalAdminId property and that the property values match on each node in
the cluster.
addNode command fails with ″doMergeConfig failed″ error
When attempting to federate a WebSphere Portal node, the addNode command
might fail with the following error:
Chapter 1. Troubleshooting 29
ADMU0040E: Exception on MBean invocation ...
...
com.ibm.websphere.management.exception.AdminException: doMergeConfig failed
This error is caused in turn by a ″Too many open files″ error.
Solution: Increase the number of files that you can open at the same time by using
the ulimit command, as described on the WebSphere Application Server
support site:
The addNode command with portal installed on node fails with
error ADMU0040E MBeanException ″doMergeConfig failed″ caused
by ″Too many open files″
Network error causes cluster install to fail
Problem: A network error that interrupts the connection between the deployment
manager and the node can cause your cluster installation to fail. The
following is an example of a network error although you may receive a
different error depending on where the network error occurs:
[wsadmin] WASX7017E: Exception received while running file "/opt/IBM/Portal/PortalServer/config/was/wp_ModifyEarAttributesWpsJndiWpsDs.jacl";
[wsadmin] org.apache.soap.SOAPException: [SOAPException: faultCode=SOAP-ENV:Client; msg=Broken pipe; targetException=java.net.SocketException
Solution: The installation program cannot detect the network error and recover.
Therefore, you must run the task that fails manually or uninstall the
cluster and then reinstall.
Global settings cannot be set in a cluster by using the XML
configuration interface
Problem: The XML configuration interface fails with the following error when you
try to set global settings in a clustered environment.
<status element="[global-settings]" result="failed">
<message id="EJPXA0043E">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0043E: An error occurred while creating or updating the resource.
[global-settings]</message>
<message id="EJPEB0002E">com.ibm.wps.command.CommandException:
EJPEB0002E: An exception occurred.</message>
<message>java.security.PrivilegedActionException: java.lang.NullPointerException</message>
</status>
Cause: The global settings are stored in the WebSphere Application Server (WAS).
For changes to the global settings a WAS API call is invoked. During this call the
following exception is thrown in the clustered environment:
Caused by: java.lang.NullPointerException
at at com.ibm.wps.services.ServiceHelper$4.run(Unknown Source)
at at com.ibm.ws.security.auth.distContextManagerImpl.runAs(distContextManagerImpl.java:2782)
... 43 more
Solution: To configure these settings, configure them directly in the administrative
console, as described in Setting configuration properties.
Cluster member startup does not complete due to ″Waiting for
HAManager″ error
When attempting to start a cluster member, the startup process appears to be
suspended and does not complete, and the SystemOut.log file displays the
following error:
CWRLS0030W: Waiting for HAManager to activate recovery processing for local WebSphere server
30 Troubleshooting guide
The high availability manager for WebSphere Application Server is unable to
establish communication due to a port conflict on the DCS_UNICAST_ADDRESS
port used by the cluster member.
Solution: Complete the following steps to correct this problem:
1. Log in to the deployment manager’s administrative console.
2. Click Servers → Application Servers, and select the server that
corresponds to the cluster member that is failing to start.
3. Click Ports, and then click DCS_UNICAST_ADDRESS.
4. Modify the port number to a unique port number.
5. Click Apply, and save your configuration changes.
6. Restart the cluster member.
Troubleshooting databases
This section contains information that can assist you in preventing, identifying, and
correcting problems related to WebSphere Portal. For information related to specific
components, see the appropriate troubleshooting topic.
v “Problem: Unable to connect to database”
v “Problem: When using multi-rows in a database, you cannot have application
data objects referencing each other.” on page 32
v “Problem: Unsuccessful execution error in IBM DB2 Universal Database for
z/OS” on page 32
v “Problem: SQL error SQL0969N in SystemErr log with DB2 for z/OS” on page
32
v “Problem: Database transfer fails when transferring multiple domains” on page
32
v “Problem: Database Transfer fails on Oracle during LikeMinds table creation” on
page 33
v “WebSphere Portal fails to start when running on Cloudscape” on page 33
Problem: Unable to connect to database
When attempting to connect to a database using a password that is about to
expire, you might receive connection errors.
If you are trying to connect to a database using a valid username and password
but are receiving a connection error, it might be that you are using a password that
is about to expire. When WebSphere Portal tries to make a connection to the
database, a warning message is returned. This is not what WebSphere Portal was
expecting and will, therefore, give a connection error.
Solution: You can solve this by manually resetting the password for your database
user from within the database management system. This will stop the warning
messages and allow WebSphere Portal to connect to the database without a
problem.
A better solution, which helps to prevent this situation, is to use a special database
user ID with a non-expiring password, as described in Configure base portal into a
WebSphere base application server node: Transfer database - Definitions.
Chapter 1. Troubleshooting 31
Problem: When using multi-rows in a database, you cannot have
application data objects referencing each other.
When using multi-rows in a database, you cannot have application data objects
referencing each other which causes circular references.
Solution: Do not use multi-row schema for a session database.
Problem: Unsuccessful execution error in IBM DB2 Universal
Database™ for z/OS
If you have not enabled the database table spaces, the following error will occur
during installation:
SQL0904N Unsuccessful execution caused by unavailable resource. SQLState=57011
Solution: If this error occurs, create a cataloged VSAM linear database for the table
space or use the STOGROUP keyword when creating the table space. See the
instructions in Creating databases and users in DB2 for z/OS.
Problem: SQL error SQL0969N in SystemErr log with DB2 for
z/OS
The following error might appear in the SystemErr.log:
SQL0969N There is no message text corresponding to SQL error "-873" in the
message file on this workstation. The error was returned from module
"DSNX0END" with the original tokens. SQLSTATE=53090
Solution: This error occurs when the DB2 Content Manager databases required by
Personalization were created with one CCSID, and the resource tables are in a
different database that has a different CCSID. DB2 Content Manager databases
should be created with CCSID UNICODE, and all the tables used with
Personalization should be in databases with the same CCSID.
Problem: Database transfer fails when transferring multiple
domains
When transferring from one database to another, the transfer may fail if the
properties are not set correctly.
Solution: When transferring from one database to another, if the DbUser, DbUrl,
and DbPassword properties are not the same across domains, the DataSourceName
value must differ from the DataSourceName values of the other domains. The
datasource values should be changed if any domain has a different user, password,
or URL value than another domain.
For example, if transferring from the default database to DB2, use the same
datasource for all domains if the DbUser, DbUrl, and DbPassword for those domains
are the exact same. If any of these differ, that domain must be different then the
rest.
32 Troubleshooting guide
Problem: Database Transfer fails on Oracle during LikeMinds
table creation
When transferring to Oracle, you may get the following error:
BUILD FAILED
file:../config/inclueds/lmdb_cfg.xml:414:ERROR: Error during the execution of sql
files
Solution: Wait a few moments and restart the transfer. This error occurs because of
a locking issue with Oracle that can occur during table creation.
WebSphere Portal fails to start when running on Cloudscape
Problem: The Cloudscape environment allows only one JVM process to access the
Cloudscape database. If another instance has already booted the database,
WebSphere Portal might fail to start with the following error in the SystemOut.log:
Caused by: java.sql.SQLException: Failed to start database ’/opt/IBM/WebSphere/PortalServer/cloudscape/wpsdb’, see the next exception for details.DSR
Solution:
1. Ensure that the WebSphere Portal server has been stopped.
2. Verify that you do not have other JDBC client programs running on the
database instance.
3. If there are no connections to Cloudscape, delete the files db.lck and dbex.lck
from the path portal_server_root/cloudscape/wpsdb, where wpsdb is the default
Cloudscape database name.
4. Restart the WebSphere Portal server.
Error received when transferring data to an Oracle database
using the Turkish locale
Problem: when running database transfer to Oracle when using the Turkish locale,
an error is received that there is an invalid username and password.
Solution: In the file wpconfig_dbdomain.properties, specify the value of the user
name in uppercase.
Troubleshooting security
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Problem: When using Active Directory, resetting an attribute to an empty string
does not work” on page 34
v “Problem: The ″<″ and ″>″ characters display incorrectly” on page 34
v “Problem: Pipe character used with the Credential Vault” on page 35
v “Problem: Special characters limitation in Member Distinguished Name” on
page 35
v “Problem: Unable to see pages in Pixo browser” on page 35
v “Problem: Browser back button can show secured page after logout” on page 36
v “Problem: Debugging the IBM Tivoli Access Manager for e-business Login
Module” on page 36
Chapter 1. Troubleshooting 33
v “Problem: Single sign-on not functioning between WebSphere Portal and other
applications on the same WebSphere Application Server installation” on page 36
v “Problem: When using Lotus Domino, cannot create users and groups” on page
37
v “Problem: Collaborative portlets require additional configuration for
compatibility with eTrust SiteMinder ” on page 37
v “Problem: Collaborative portlets require additional configuration for
compatibility with Tivoli Access Manager ” on page 38
v “Problem: Collaborative portlets require an interim fix to STlinks applet to work
in Mozilla” on page 38
v “Problem: Distinguished names containing escape characters cause people
awareness to function incorrectly in several Domino and Extended Products
Portlets” on page 38
v “Problem: SSO for Domino and Extended Products fails for users containing
LDAP special characters in their distinguished names” on page 38
v “Problem: Data backend exception while creating new users” on page 39
v “Problem: SSL Connection fails after configuring SSL to LDAP” on page 39
v “Problem: Membership of deleted user not removed from target repository” on
page 40
v “Problem: Users and groups not moved to new registry after running enable
security tasks of Customization Dialog” on page 40
v “Problem: Validation of userid does not work as expected” on page 40
v “Problem: validate-ldap task fails if password contains $” on page 40
Problem: When using Active Directory, resetting an attribute to
an empty string does not work
It is not possible to set an attribute to an empty string in combination with using
the Active Directory LDAP. For example, in the Selfcare portlet, you cannot reset
the preferred language to Nothing selected if the attribute is retrieved from Active
Directory where the preferred language is set to a specific language.
Solution: This is a limitation with Active Directory.
Problem: The ″<″ and ″>″ characters display incorrectly
In WP ConfigurationService, there is a flag to enable or disable the Cross Site
Scripting (CSS) security protection.
Solution: It might be desirable to disable CSS if you use form input fields
containing ″less than″ and ″greater than″ signs. During the POST of a form
containing such characters to a portlet, the output of the ″<″ will be seen as ″<″
and ″>″ as ″>″. Other non-alphabetical characters like ″&″, single quotes, and
double quotes appear as intended. Disabling CSS allows the ″<″ and ″>″ characters
to appear as intended. Characters such as ″<″ and ″>″ will be encoded to minimize
the security risk of typing markup in a field that could disrupt portal content.
Disabling CSS is done at the portal level and not just the portlet level. While it
might be convenient to disable the CSS protection in some circumstances, it
exposes a potential vulnerability when passing form input into a Web application.
Some secure programs could unwittingly accept data from an untrusted user (the
attacker) and pass that data on to a different user’s application (the victim). If the
34 Troubleshooting guide
secure program does not protect the victim, the victim’s application (in this case,
his or her Web browser) can then process that data in a way harmful to the victim.
This is a particularly common problem for all web applications using HTML or
XML, where the problem is known by several names including ″cross-site
scripting,″ ″malicious HTML tags,″ or ″malicious content,″ and can happen on SSL
and non-SSL connections. While activating portal CSS protection automatically
prevents a good deal of CSS attacks, it cannot prevent all of them. The web
developer must always validate all user-provided data and correct character
escaping prior to writing user-provided data to the markup stream. With a
successful CSS attack, the hacker could gain complete access to some pages. Here
are some of the problems associated with not implementing this security feature:
v SSL-encrypted connections might be exposed
v Attacks might be persistent through poisoned cookies
v Attacker might access restricted web sites from the client
v Domain-based security policies might be violated
v Use of less-common character sets might present additional risk
v Attacker might alter the behavior of forms
See http://www-128.ibm.com/developerworks/web/library/wa-secxss/?ca=dnt-55 for additional information.
The relevant entry in WP ConfigurationService is:
# Flag whether Cross-Site-Scripting security protection is turned on.
#
# Default: true
security.css.protection = true
Verify this property value entry in Configuration service, as described in Setting
configuration properties.
Problem: Pipe character used with the Credential Vault
Solution: Only the names of vault segments, vault slots, and resources cannot use
the pipe character. The vertical or | character can be used in the description.
Problem: Special characters limitation in Member Distinguished
Name
Member Manager cannot be used to create a member entry in a repository if the
entry has RDN attributes with values which contain the following special
characters: ″#″, ″,″, ″+″, ″″″, ″\″, ″<″, ″>″, or ″;″.
Solution: If you want to allow the creation of special characters in member entries,
you must create the entry directly into the repository not using Member Manager
although Member Manager can be used to read, update, remove, and search the
entry. For example, for an LDAP server, use an LDAP server tool or another LDAP
application instead of Member Manager to create the entry into the LDAP server.
Problem: Unable to see pages in Pixo browser
When using the Pixo Internet Microbrowser 2.1 device emulator on a PC, you will
not be able to see any pages on your secure portal. This problem is caused by a
defect in the Pixo simulator that affects supported cookies. WebSphere Portal with
WebSphere Application Server global security enabled requires two cookies,
Chapter 1. Troubleshooting 35
JSESSIONID and LtpaToken . The JSESSIONID cookie is used to identify the
WebSphere Portal session in the browser. LtpaToken is used to identify the user for
WebSphere Application Server global security. Although two valid cookies are set
for this domain, the Pixo browser only sends the most recently set cookie, which
causes LtpaToken to replace JSESSIONID. Although LtpaToken allows the user to
access WebSphere Portal, the browser is unidentified; therefore, the user will not be
able to see any pages.
Solution: Use a real device, or use a different device emulator for cHTML testing.
Problem: Browser back button can show secured page after
logout
With some browsers you might be able to view the information from a previous
portal session by using the back button after logout. When you log out and click
the back button, you can see the page that was last viewed.
Example scenario: You view an e-mail and click Log out. The portal returns to the
Login panel. If you then click the back button, you might be able to view the
e-mail again, depending on your browser.
Note: The problem concerns only the display and view of data. The portal or the
displayed data cannot be modified as clicking the back button does not
undo the logout.
Cause: When you click the back button, the browser returns to the data cached by
the browser.
Solution: Users can prevent the display of secured pages by either closing the
browser after logout or clearing the browser cache.
Problem: Debugging the IBM Tivoli® Access Manager for
e-business Login Module
Solution: The WebSphere Application Server Administrative Console maintains the
Login Modules for WebSphere Portal. To debug the Tivoli Access Manager
supplied PDLoginModule, access the WebSphere Application Server Administrative
Console, look for the application Portal_Login JAAS Login, and add a custom
property to PDLoginModule with a property name of debug and a value =true.
The output is written to standard out for the Portal Server Application Server.
Problem: Single sign-on not functioning between WebSphere
Portal and other applications on the same WebSphere
Application Server installation
Under certain circumstances, there is a problem with single sign-on between
WebSphere Portal and other applications on the same WebSphere Application
Server installation. When this problem occurs, you are unable to log into an
application on an application server; for example, the WebSphere Application
Server Admin console and then logging into a portal running on the same
application server without renewed authentication (single sign-on fails). The portal
displays a misleading error message saying that the user’s portal session has timed
out. The portal then prompts the user to log in again.
36 Troubleshooting guide
Cause: The session cookie of the other application is not properly specified (the
cookie path is too general) and is therefore also sent to the portal. In most cases,
the cookie is specified as a simple slash (/). The portal application mistakes this as
an old, invalid portal session cookie.
Solution: Follow these steps to ensure that the application’s session cookie is
scoped to that application only:
1. Log in to the WebSphere Application Server Administrative console.
2. Navigate to Applications>Enterprise Applications>respective
application>Session Management, where respective application is the application
with which single sign-on does not work.
3. Click the Enable Cookies link (not the check box).
4. Set the cookie path value to the complete application base path. For example,
the Administrative console of the application server would be /admin.
5. Click Apply to save the changes and then restart the application.
Problem: When using Lotus Domino, cannot create users and
groups
If you are using IBM Lotus® Domino® and edit the access control list of NAMES.NSF
so that ″Maximum Internet name and password″ is set to ″Reader″, you may notice
that you are no longer able to create users and groups in WebSphere Portal.
Solution: The recommended setting for ″Maximum Internet name and password″
is ″Author″ or higher. By setting this field to ″Reader″, you would be overriding
the regular settings in the access control list and thereby limiting the
Author/Editor access that is necessary for WebSphere Portal to function
successfully with Lotus Domino as the LDAP server.
Note: To access the ″Maximum Internet name and password″ setting, open
NAMES.NSF with a Lotus Notes client by selecting File → Database → Open
and then File → Database → Access Control → Advanced. Options for this
setting range from ″No Access″ to ″Manager″.
Problem: Collaborative portlets require additional configuration
for compatibility with eTrust SiteMinder
Many features of the Domino and Extended Products Portlets will not work if your
eTrust SiteMinder-protected portal environment is not properly configured.
Problems include failure of awareness, failure of the IBM Lotus Sametime® server
to authenticate with the Lotus Web Conferencing portlet, failure of the My Lotus
QuickPlaces portlet to connect to the IBM Lotus QuickPlace® server, and inability
of the Domino Web Access and Lotus Notes View portlets to find mail files for the
current user.
Solution: You need to edit the CSEnvironment.properties file to use the eTrust
SiteMinder token. See Customizing Collaborative Services user credentials for
eTrust SiteMinder. For more details, refer to the following troubleshooting technote:
Technote 1190655: Awareness, connection and authentication problems if
Collaborative Portlets v5.1 not configured for eTrust SiteMinder properly
Chapter 1. Troubleshooting 37
Problem: Collaborative portlets require additional configuration
for compatibility with Tivoli Access Manager
Many features of the Domino and Extended Products Portlets will not work if your
Tivoli Access Manager-protected portal environment is not properly configured.
Problems include failure of awareness, failure of the Lotus Sametime server to
authenticate with the Lotus Web Conferencing portlet, and failure of the My Lotus
QuickPlaces portlet to connect to the Lotus QuickPlace server.
Solution: An interim fix is available on the IBM Support Web site. Refer to the
following troubleshooting technote:
Technote 1191185: Awareness, Connection and Authentication Problems if
Collaborative Portlets v5.1 not Configured for Tivoli Access Manager
Problem: Collaborative portlets require an interim fix to STlinks
applet to work in Mozilla
In the Mozilla browser, many problems in collaborative portlets result from the
version of the STlinks applet configured on the IBM Lotus Sametime server, as well
as versions of other related files. For example, a timing problem prevents the Who
Is Here and Lotus Web Conferencing portlets from working if deployed on the
same page, awareness may fail, the Chat button in the Domino Web Access portlet
may not work, and the Who Is Here portlet may be unable to display the
membership list.
Solution: An interim fix for the STlinks applet is available on the IBM Support
Web site. Corrected files are available to solve the problems above. Refer
to the following troubleshooting technote:
Technote 1191188: Lotus Collaborative Portlets v5.1 Exhibit Problems when
Accessed via Mozilla Browser
Problem: Distinguished names containing escape characters
cause people awareness to function incorrectly in several
Domino and Extended Products Portlets
Portlets with this problem include Lotus Web Conferencing, My Lotus QuickPlaces,
and Sametime Contact List.
Solution: An interim fix is available on the IBM Support Web site. Read the
following technote:
Technote 1191190: People Awareness in v5.1 of Lotus Collaboration Center Portlets
Does not Function Properly
Problem: SSO for Domino and Extended Products fails for users
containing LDAP special characters in their distinguished names
LDAP (Lightweight Directory Access Protocol) special characters existing in
distinguished names of either users or groups prevent Single Sign-On (SSO) from
working correctly between WebSphere Portal, IBM Lotus Sametime, IBM Lotus
QuickPlace and Lotus Domino databases unless configuration fixes are applied to
the servers.
38 Troubleshooting guide
For example, a user whose name contains special characters may be asked to
authenticate with the Mail, Calendar, or Address book instances of the Domino
and Extended Products Portlets. The LDAP special characters are:
v A space or # character occurring at the beginning of the string
v A space character occurring at the end of the string
v One of the characters ″,″, ″+″, ″″″ , ″\″, ″>″, ″<″, or ″;″
Also, the / and @ are Lotus Domino special characters and will cause the same
problems without the interim fixes available from Lotus Technical Support.
Solution: Interim fixes are available on the IBM Support Web site. Refer to the
following troubleshooting technote:
Technote 1191194: SSO for Domino Extended Products Fails for Users Containing
LDAP Special Characters in their Distinguished Names
Problem: Data backend exception while creating new users
Within WebSphere Portal you can set a password’s minimum and maximum
length. If the set password lengths differ from your LDAP server’s policy, you
might see the following exception when creating a user:
EJPSG0015E: Data Backend Problem com.ibm.websphere.wmm.exception.WMMSystemException:
The following Naming Exception occurred during processing:
"javax.naming.OperationNotSupportedException: [LDAP: error code 53 - 0000052D:
SvcErr: DSID-031A0FBC, problem 5003 (WILL_NOT_PERFORM), data 0
]; remaining name ’cn=see1anna,cn=users,dc=wps510,dc=rtp,dc=raleigh,dc=ibm,dc=com’;
resolved object com.sun.jndi.ldap.LdapCtx@7075b1b4".
Solution: Check and/or modify the puma.PASSWORD.min and puma.PASSWORD.max
properties within Puma. The keys should match your LDAP server’s
policy.
Problem: SSL Connection fails after configuring SSL to LDAP
If you configured the connection to LDAP via SSL in Member Manager, connection
fails because of invalid or missing certificates.
When a certificate truststore is configured within the wmm.xml file via the
sslTrustStore property, this truststore will be used as default truststore by all
applications in the Portal Server Java Virtual Machine. This includes all portlets
deployed on the Portal Server as well as the themes and skins. If you used the
default Java truststore, cacerts, to store your trusted certificates before switching to
LDAP via SSL, these certificates will no longer be found, which causes the SSL
connection to fail.
Solution: Use one of the following three solutions:
v Store the trusted certificate required for your LDAP SSL connection in the cacerts
truststore and configure Member Manager to use this truststore.
v Store the trusted certificate required by your application in the truststore used
by Member Manager for the LDAP SSL connection.
v Adapt your application code to explicitly specify the truststore to use when
opening the SSL connection.
Chapter 1. Troubleshooting 39
Problem: Membership of deleted user not removed from target
repository
When deleting a user/group from an LDAP using the WebSphere Portal
administrator functions, some LDAP servers do not clean up the user/group’s
membership. Therefore, if a new user/group is created with the same name, it is
placed in the existing membership. For example, the new user would belong to the
same groups as the deleted user.
Solution: Configure Member Manager to update the repository. Follow these steps
to enable this feature:
1. Open the wmm.xml file.
2. Add updateGroupMembership=″true″ as an attribute to the ldaprepository tag.
Note: For IDS on z/OS, this parameter needs to set to true in the wmm.xml file.
Problem: Users and groups not moved to new registry after
running enable security tasks of Customization Dialog
The Customization Dialog’s enable security configuration tasks do not move users
and groups from one registry to another. For example, running the Customization
Dialog task for enabling security using an LDAP registry without realms does not
move users and groups from the default database to an LDAP user registry.
Solution: Manually move users and groups to the final user registry as soon as
possible after installation. If you use an LDAP user registry, use registry-specific
tools to re-create the users and groups. If you use a database user registry
configuration (an IBM-supplied custom user registry), create your users and
groups after running the enable security configuration tasks using the
Customization Dialog.
Problem: Validation of userid does not work as expected
User attribute validation is only performed for mandatory attributes. These
attributes are defined in the wmmAttibutes.xml file.
Solution: Verify that the attribute you are using for the user logon id is marked as
mandatory in the wmmAttibutes.xml file.
Problem: validate-ldap task fails if password contains $
Passwords containing $ in the wpconfig.properties file cause problems because of a
limitation or special use of the $ character in ANT.
Solution: To maintain backward compatibility with older ANT releases, a single $
character encountered apart from a property-like construct (including a matched
pair of french braces) is interpreted literally; that is as $. Therefore, use the
escaping mechanism unconditionally to specify the character so that $$$$ results in
$$.
Warning: Mixing the two approaches yields unpredictable results. $$$ results in
$$.
40 Troubleshooting guide
Troubleshooting Web servers
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Problem: configure Web_server_name command fails on UNIX”
v “Problem: WebSphere Portal hangs while visiting through a local IIS 6.0 Web
server”
Problem: configure Web_server_name command fails on UNIX
When configuring a Web server on some UNIX systems, the
configureWeb_server_name.sh command might fail, with an error similar to the
following:
Configuration save is not complete, exception = com.ibm.ws.scripting.ScriptingException:
com.ibm.websphere.management.exception.ConfigServiceException:
com.ibm.websphere.management.exception.ConnectorException:
ADMC0009E: The system failed to make the SOAP RPC call: invoke
WASX7309W: No "save" was performed before the script "configureWebserverDefinition.jacl"
exited; configuration changes will not be saved.
Solution: Increase the timeout value for the type of connection you are using:
v SOAP connection: Edit the file was_profile_root/properties/soap.client.properties, and increase the value for the
com.ibm.SOAP.requestTimeout property to 6000. The value is in
seconds.
v RMI connection: Edit the file was_profile_root/properties/sas.client.props, and increase the value for the
com.ibm.CORBA.requestTimeout property to 6000. The value is in
seconds.
Problem: WebSphere Portal hangs while visiting through a local
IIS 6.0 Web server
If a CheckPoint or ZoneLab firewall is installed on your Windows system, portal
will hang when visiting through a local IIS 6.0 web server.
Solution: Uninstall the firewall and restart the server.
Troubleshooting access to the portal
This section describes problems that might occur when a user tries to log in to the
portal.
v “Problem: Portal URL does not open ” on page 42
v “Problem: Unable to connect to portal ” on page 42
v “Problem: Login attempt is unsuccessful, but no error message is displayed ” on
page 42
v “Problem: Application Error message displays when accessing the portal ” on
page 43
v “Problem: Redirected back to login screen ” on page 43
v “Problem: Login fails with a user ID that contains special characters” on page 44
v “Problem: Accessing portlets prior to authentication” on page 45
Chapter 1. Troubleshooting 41
v “Problem: Unable to log into the portal immediately after logging out” on page
45
v “Problem: User is logged out of the portal” on page 45
v “Problem: Portal does not render, HTML markup is not supported” on page 47
v “Problem: Browser returns an invalid syntax error” on page 47
v “Problem: Contextual menus show off page” on page 47
v “Problem: Browser does not finish loading page” on page 48
v “Problem: Exception message displays when attempting to log in to the portal”
on page 48
v “Problem: Portal Log in link is missing” on page 48
v “Problem: During portal migration, XmlAccess reports an
AuthorizationModelException with error code EJPSB0125E” on page 48
v
“Problem: Launch button does not work in Microsoft Internet
Explorer V 7 ” on page 49
Problem: Portal URL does not open
If you try to open the portal URL, but the browser returns a 404 message (file not
found), check the base URI and default home page.
Solution: The portal does not work unless a base URI is configured. The default
base URI is /wps . For example, if the default base URI and the default home page
were configured for the portal, you would open the URL http://hostname.example.com:10038/wps/portal, where hostname.example.com is the fully
qualified host name of the machine where WebSphere Portal is running and 10038
is the default transport port that is created by WebSphere Application Server..
Problem: Unable to connect to portal
IBM WebSphere Portal Enable for z/OS is an application server that is running on
WebSphere Application Server. If you are having trouble launching WebSphere
Portal you might want to verify that the application server was successfully
installed.
Solution: Verify that the application server is installed by starting the WebSphere
Application Server Administrative Console and look for settings that are specific to
WebSphere Portal. For example, WebSphere Portal installs the following entries in
the left panel of the Administrative Console:
v Applications > Enterprise Application > wps
v Servers > Application Servers > WebSphere_Portal
v Resources > JDBC providers > wpsdbJDBC
Problem: Login attempt is unsuccessful, but no error message is
displayed
If the login to the portal is unsuccessful, obvious error messages will usually be
displayed. Typically, the error is the result of incorrectly entering a valid user ID
and password, or, depending on the WebSphere Portal version and Fix Pack level,
an error screen requesting that the user explicitly log out of portal at the end of a
session.
42 Troubleshooting guide
Solution: In the case where login is not successful but no obvious error message is
displayed, there are several possibilities, depending on the exact symptoms and
system configuration.
If an authentication front end, such as Tivoli Access Manager is deployed and a
corresponding Trust Association Interceptor (TAI) is configured for WebSphere
Application Server, there might be an error in the configuration of the
authentication front-end component. Descriptions of how to debug that
environment are beyond the scope of this documentation; consult the appropriate
product specific documentation in this case.
If the authentication proxy and TAI are working correctly, there might be a
problem in the WebSphere Portal JAAS login processing. Activating the
com.ibm.wps.sso.*=all: will generate trace output from most of the JAAS
loginmodules supplied with WebSphere Portal. The PDLoginModule, if present, can
be traced by adding debug=true as a parameter to the loginmodule in the Portal
Login JAAS Application object in the WebSphere Application Server administrative
console.
If no authentication proxy or TAI are configured, and the symptom seen is that the
user is immediately placed back at the login form after submitting the filled-in
login form, a likely cause is that WebSphere Application Server single signon and
the associated necessary cookie enablement is not correctly configured. Verify that
your Web browser is enabled for cookies. A cookie with a valid LTPA token is
needed to access URLs that are secured by WebSphere Application Server. If the
browser is not configured to accept cookies, activate this feature. A good test is to
activate cookie prompting in the browser; the methods to do this vary from
browser to browser and are beyond the scope of this document. An LtpaToken
cookie should be seen after the login form is submitted, and the DNS domain
associated with that cookie must be correctly set to enable it to be sent back to
WebSphere Portal on subsequent requests. If the DNS domain of the cookie is not
correct, go to the WebSphere Application Server Administrative Console Security
Center, and on the Authentication Tab, make the necessary corrections. Also, note
that the single signon cookie domain must consist of at least two names separated
by a period. For example, example.com is acceptable, but example or just .com is
not.
Problem: Application Error message displays when accessing
the portal
Solution: Verify that the WebSphere Application Server is installed correctly.
Problem: Redirected back to login screen
A problem that sometimes occurs as you attempt to install WebSphere Portal is
that you might be able to activate WebSphere Portal but might not be able to log
in. Specifically, after you submit your user name and password in response to the
login screen, you are immediately redirected back to the login screen again.
Solution: Usually, this is a result of a configuration problem with the security
support of WebSphere Application Server. An easy way to diagnose this problem is
to activate cookie prompting. To resolve this problem, perform the following steps:
1. In Internet Explorer, select Tools > Internet Options.
2. Select the Security tab.
Chapter 1. Troubleshooting 43
3. Select the Web content zone that your browser uses to connect to WebSphere
Portal. Usually, this will be the Internet zone.
4. Select Custom Level. Scroll down until you see Cookies.
5. Select Prompt for both stored and per-session cookies.
6. Save and exit.
Internet Explorer should then prompt you whenever a server attempts to set a
cookie on your browser. The prompt will say Security Alert and will ask if you
will allow the Web site to place a cookie on your computer. Select the More Info
button on the prompt to display the cookie name and other information.
When you attempt to log in to WebSphere Portal, you should see the following
two cookies being set on your browser:
v JSESSIONID
v LtpaToken
You might also see a third cookie, WasReqURL, if you access /wps/myportal directly
and were redirected by WebSphere Application Server to the WebSphere Portal
login screen.
If you don’t see the LtpaToken cookie, then you will not be able to successfully log
in to WebSphere Application Server and WebSphere Portal.
If this is the case, it is possible that the problem is that the domain of the
LtpaToken cookie is not configured correctly in WebSphere Application Server. To
correct this, perform the following steps:
1. In the WebSphere Application Server Administrative Console, select Security →
Authentication Mechanisms → LTPA.
2. Select Single Signon in Additional Properties.
3. Verify that Single Signon is enabled by checking the box, except on very rare
occasions when using IBM Tivoli Access Manager for e-business WebSEAL as
an authentication proxy in front of WebSphere Application Server and
WebSphere Portal.
4. Also, the Domain must be set such that a cookie marked with that domain will
be sent to the browser and then returned on subsequent requests from the
browser to WebSphere Application Server.
Problem: Login fails with a user ID that contains special
characters
Solution: Verify that your user ID contains valid characters. A valid user ID for
WebSphere Portal might contain only the characters a-z, AZ, period (.), and
underscore ( _ ). Diacritics, such as the umlaut, are not allowed.
When you signed up as a portal user or when the portal administrator enrolled
you as a user, you completed the user information form. The user ID field is
limited to the valid characters described in this section, but you can specify other
characters in the First Name and Last Name fields.
If the user IDs of your portal users contain special characters, for example,
double-byte characters, make sure that the property
com.ibm.CORBA.ORBCharEncoding=UTF8 has been set on the administrative server
and all application servers. For more detail, see the documentation for WebSphere
Application Server.
44 Troubleshooting guide
Problem: Accessing portlets prior to authentication
By default, portlets placed on a page that does not require authentication do not
have access to a portlet session (PortletSession object). This can cause problems
when the portlet attempts to access the session without first checking to make sure
that the session is available. Or, the portlet might write an error message to the
portlet log or the user interface if the session is not available.
Solution:
There are two possible solutions:
v Enable session tracking for anonymous users
In the Navigator Service change the public.session property value to true. For
details about how to do this refer to Setting configuration properties.
v Move the portlet to a page that requires authentication
This solution not only solves the session problem, but ensures that the user is
authenticated.
Problem: Unable to log into the portal immediately after logging
out
If the Authorization failed error occurs when you try to log in to the portal
immediately after logging out, the portal system time is ahead of the client system
time.
Solution: Set the correct time on the client system clock.
Problem: User is logged out of the portal
There are two reasons why a user can be logged out by the portal:
v The browser window is inactive for a time period that exceeds the timeout.
v The user’s LTPA token expires.
The following sections provide solutions for both problems.
Solution: Timeout by inactivity in the portal browser window - Configuring
session management by level
If a user opens a portlet in a secondary browser window, interactions with that
portlet are not sent to the portal. As a result, users could exhaust their portal
session in the secondary window and be logged out of the portal, even if the
portal window is still open.
You can configure session management at the Web container level. This includes
configuring the duration of portal sessions. When you configure session
management at the Web container level, all applications and the respective Web
modules in the Web container normally inherit that configuration, setting up a
basic default configuration for all applications and Web modules below it.
However, you can set up different configurations individually for specific
applications and Web modules that vary from the Web container default. These
different configurations override the default for these applications and Web
modules only.
Chapter 1. Troubleshooting 45
Note: When you overwrite the default session management settings on the
application level, all the Web modules below that application inherit this
new setting unless they too are set to overwrite these settings.
To change the duration of portal sessions by level, perform the following steps:
1. Open the Administrative Console for WebSphere Application Server.
2. Select the level that this configuration applies to:
v For the Web container level:
a. Click Servers → Application Servers
b. Select a server from the list of application servers
c. Under Additional Properties, click Web Container
v For the enterprise application level:
a. Click Applications → Applications
b. Select an applications from the list of applicationsv For the Web module level:
a. Click Applications → Enterprise Applications
b. Select an applications from the list of applications
c. Under Related Items, click Web Modules
d. Select a Web module from the list of Web modules defined for this
application3. Under Additional Properties, click Session Management
4. Make whatever changes you need to manage sessions
5. If you are working on the Web module or application level and want these
settings to override the inherited Session Management settings, under General
Properties, select Overwrite.
6. Click Apply and Save.
You can also access this information online at http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.websphere.base.doc/info/aes/ae/tprs_cnfs.html. For more information, refer to the following URL:
http://publib.boulder.ibm.com/infocenter/wasinfo/topic/com.ibm.websphere.base.doc/info/aes/ae/uprs_rsession_manager.html.
Solution: Expiration of the user’s LTPA token
During the portal installation, the LTPA token expiration is set to 120 minutes.
Users who are in session with the portal for more than two hours are logged out
and will have to re-authenticate to continue using the portal. To change this
setting, perform these steps:
1. Open the Administrative Console for WebSphere Application Server.
2. On the menu bar, click Security → Global security → Authentication →
Authentication mechanisms → LTPA.
3. Modify the timeout value as required.
4. Click Apply.
5. Click the Save link.
6. Click the Save button.
7. Close the Administrative Console.
8. Restart the Administrative Server for WebSphere Application Server for the
changes to take effect.
46 Troubleshooting guide
Problem: Portal does not render, HTML markup is not supported
The Supported Markups portlet in Administration is used to add, remove, and
edit markup languages supported by the portal. It is possible that an administrator
could remove or change HTML as a supported markup. If this happens, the portal
user interface will no longer render in any of the supported Web browsers.
Solution:
Follow these steps to recover from this error.
1. Make sure the portal is started.
2. Create an XML file in the portal server config directory. For example, create
recoverHTML.xml in the following WebSphere Portal installation directory:
v z/OS: portal_server_root/config/work
3. Insert the following XML markup for the file content and save the file.
<request
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PortalConfig_1.2.xsd"
type="update" create-oids="true">
<portal action="locate">
<markup action="update" active="true" default-charset="UTF-8" objectid="html"
mimetype="text/html" name="html">
<localedata charset="UTF-8" locale="en" prefix="markup.html">
<url>file:///$server_root$/config/work/SetupPortal_en.properties</url>
</localedata>
</markup>
</portal>
<status element="all" result="ok"/>
</request>
4. From a command prompt, change to the WebSphere Portal installation
directory:
v For z/OS: portal_server_root/bin
5. Run the XMLAccess command against the XML file you created. For example:
./xmlaccess.sh -in portal_server_root/config/work/recoverHTML.xml -user adminID -pwd adminPassword
6. HTML is supported by the portal once the command has completed
successfully. Log back into the portal and reopen the Supported Markups
portlet to view the changes.
Problem: Browser returns an invalid syntax error
Some browsers might return a page not found - invalid syntax error when
attempting to access WebSphere Portal.
Solution: Certain browsers require that you include the URL type, such as http://,
before entering URLs with non-standard ports. Always include the URL type when
entering the portal URL to prevent this error.
Problem: Contextual menus show off page
If you click the arrow on the Launch button for the main menu, or click one of the
arrows for a contextual menu on a page, the menu may display far away from the
selection arrow.
Chapter 1. Troubleshooting 47
Solution: The menus display closer to the buttons if you use Internet Explorer
Version 7.0.
Problem: Browser does not finish loading page
When using Internet Explorer to access WebSphere Portal, the browser appears to
finish loading the page (the icon stops spinning.) before the page actually is
finished.
Solution: This is a known issue with the Internet Explorer browser. For details see
http://support.microsoft.com/kb/183110.
Problem: Exception message displays when attempting to log in
to the portal
The following exception occurs when a user attempts to log in to the portal:
2005.01.28 06:30:14.984 E com.ibm.wps.datastore.impl.DataStoreContext handleException
EJPDB0031E: Object was not found in database
Solution: This exception occurs when a user is simultaneously logged into the
portal multiple times. The user must be properly logged out before the login
attempt will be successful.
Problem: Portal Log in link is missing
The Log in link could be missing because the page that contains the Login portlet
is inactive. Pages are made inactive whenever they are being edited in Edit Layout.
Solution: Click Done in Edit Layout.
If you cannot complete the Edit Layout process for some reason, such as a session
timeout, you can reactivate the login page using xmlaccess. The following example
would be appropriate for a default Portal installation:
<content-node action="update" active="true" uniquename="wps.Login" />
Problem: During portal migration, XmlAccess reports an
AuthorizationModelException with error code EJPSB0125E
This exception indicates that the previous version contains invalid role assignments
that cannot be created within the current version. The following role assignments
for the Anonymous Portal User are considered invalid in the current version:
v Privileged User@somepage
v Editor@somepage
v Manager@somepage
v Administrator@somepage
All those role assignments would allow the anonymous user to modify existing
portal content which is not supported by the portal runtime.
Solution: In the previous version, change all of the above role assignments into
User roles; see Roles for information.
48 Troubleshooting guide
Problem: Launch button does not work in Microsoft Internet
Explorer V 7
If users use Microsoft Internet Explorer Version 7, the portal Launch button might
not work.
Cause: WebSphere Portal identifies the browsers that are used with clients. For
more information about this refer to Supporting new clients. The order of these
clients determines how the browser of the user is recognized.
Solution: Reorder the clients to the appropriate order. Proceed by the following
steps:
1. Go to the Administration page. To do this while the Launch button does not
work, use the link at the bottom of the portal page, or use a different browser.
2. Select Portal Settings → Supported Clients.
3. Reorder the clients to the following order:
(.*(B|b)ot.*)|(.*BOT.*)|(.*(S|s)pider.*)|(.*(S|s)earch.*)|(.*(C|c)rawl(er)?.*)|(.*(G|g)rabber.*)|(.*(Y|y)ahoo.*)|(.*(S|s)lurp.*)|(.*Lycos.*)|(.*Wget.*):
.*MSIE 7.0.*
.*MSIE 6.0.*
.*MSIE.*
. . . . .
By alternative, you can also use the XML configuration interface to reorder the
clients.
Troubleshooting administration
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Troubleshooting issues related to using or administering the portal” on page 50
– “Problem: Browser switches to another session when multiple users are
logged in from the same client” on page 50
– “Problem: Application error for Edit Layout and Content” on page 50
– “Problem: Portlet contents are blank” on page 51
– “Problem: An error message after an LTPA timeout that follows a session
timeout” on page 51
– “Problem: Receiving session timeout screen ” on page 51
– “Problem: Browser refresh forces a portlet transaction” on page 51
– “Problem: Cannot use the XML configuration interface if it is externalized in
security” on page 52
– “Problem: Link to launch Edit mode of a portlet disappears” on page 52
– “Problem: Portlet deployment fails due to transfer or timeout problems” on
page 52
– “Problem: Extracting a JNDI namespace in portal” on page 53
– “Problem: Error occurs when exporting files from various portlets” on page
54
– “Problem: Error message EJPPH0004E on renamed wps.ear file” on page 54v “Troubleshooting issues related to national language support” on page 54
– “Problem: Issues with browsers displaying DBCS characters in selection
boxes” on page 54
Chapter 1. Troubleshooting 49
– “Problem: Issues with information center and Portal Help search” on page 55
– “Problem: Issues with Microsoft Internet Explorer in a Japanese environment”
on page 55
– “Problem: Message corruption for Japanese locale in Portal Scripting Interface
with interactive mode” on page 55
– “Problem: Message corruption for Japanese locale in ConfigTrace.log” on page
55v “Problem: Search Crawler OutofMemory error” on page 56
Troubleshooting issues related to using or administering the
portal
This section describes problem that can occur when using or administering the
portal.
Problem: Browser switches to another session when multiple
users are logged in from the same client
If a user, such as the portal administrator, logs in to the portal, leaves that login
active, and then logs in from another instance of the same browser but using a
different user ID, the second instance of the browser might switch to the first
user’s session and other problems might occur.
Solution: If you need to log in as different users on the same client, use one of the
following methods to avoid this problem:
v If you do not need to maintain session data for any of the user logins, log off
from one user account before you log in to the other user account.
v If you need to maintain active sessions for each user, use a different browser
type for each user session. For example, use Netscape Navigator for one login
and Microsoft Internet Explorer for the second login.
Problem: Application error for Edit Layout and Content
An application error might occur when you use the Edit Page task. The sequence
of events that result in the problem are:
1. A new user signs up or enrolls for the portal.
2. The user logs in.
3. The user selects the page to work with.
4. The user selects the Edit Page.
5. The user selects a portlet on the page and then clicks the edit portlet icon. The
edit portlet dialog is displayed in a separate window.
6. The user edits the portlet and then clicks the OK button. The edit portlet
window closes.
7. The user clicks the edit portlet icon a second time. This time, the edit portlet
dialog displays in a separate window, but with the message There has been an
application error.
Solution: If this problem occurs, the user should log off and then log in again.
Then the problem will not occur again.
50 Troubleshooting guide
Problem: Portlet contents are blank
When a portlet Web application is unavailable, for example because it was stopped
in the application server, the corresponding portlets will not show an error
message but just display no content. In this case, the log file will show one of the
following error messages:
v PEPC0001E: ServletContext belonging to servlet XX could not be found.
v PEPC0003E: ServletContext lookup for XX returned the portal’s context. It has to
be a different one.
Solution: Make sure the enterprise application is started by using the application
server’s administrative console.
Problem: An error message after an LTPA timeout that follows a
session timeout
After an LTPA timeout following a session timeout, an IllegalArgException error
might be displayed and a new login is required.
Solution: Refresh the Web browser by doing one of the following:
v For Netscape users, press and hold the Shift key and click Reload
v For Internet Explorer users, press and hold the Shift key and click Refresh.
Problem: Receiving session timeout screen
When a user from another application server instance within the single signon
domain of WebSphere Portal with a Session cookie that has the name JSESSIONID
and a cookie path that matches the portal URL (for example, the default value /)
accesses the WebSphere Portal protected area (for example, myportal), the user will
see the session timeout screen. This is because WebSphere Portal cannot distinguish
if the cookie sent by the browser was created by itself or by another application
server instance.
Solution: To prevent this problem, the cookie path has to be adjusted so that it can
be distinguished from the WebSphere Portal URL in the other Application Server
instances that share the same single signon domain. Use the Session Management
settings in IBM WebSphere Application Server Administration to specify a unique
cookie path for the JSESSIONID cookie.
Note: If you specify the cookie path using ″overwrite″ option in the session
management administration screen at a level other then the web container
level, you will have to again specify distributed session settings at that level
even though they might already be defined at the web container level.
Problem: Browser refresh forces a portlet transaction
For portlets that use String-based actions, refreshing the browser could cause the
portlet to re-execute its action, creating a problem in some transactional portlets.
For example, a user clicking refresh could inadvertently trigger an action that
updates the quantity of an item in a shopping cart.
Solution: Modify the portlet by adding the following configuration parameter and
value:
com.ibm.wps.portlet.action.redirect = true
Chapter 1. Troubleshooting 51
This allows the page and portlet to be reloaded without the action parameters in
the URL. You can add and set configuration parameters by clicking
Administration, Portlets, then Manage Portlets. Select the portlet to be modified
and click Modify parameters.
Problem: Cannot use the XML configuration interface if it is
externalized in security
If the virtual resource XML_ACCESS that represents access to the XML configuration
interface is put under protection of an external security manager, you can no
longer use the XML configuration interface.
Solution: If the access rights of WebSphere Portal are externalized to an external
security manager, such as IBM Tivoli Access Manager for e-business, make sure
that the XML configuration interface virtual resource is not externalized.
Problem: Link to launch Edit mode of a portlet disappears
When you use the Edit Layout portlet to edit a page, the page is deactivated and
the link to launch the Edit mode of a portlet on that page disappears.
Cause: A page is deactivated immediately after you perform an action in the Edit
Content and Layout portlet, for example, Add Portlets or Move Portlets/container.
Solution: Once the page is deactivated after you an action, you need to click Done
to leave the page. This activates the page again. When you click the Edit Page link,
the Edit Portlet link is displayed.
Problem: Portlet deployment fails due to transfer or timeout
problems
Deploying a portlet application by using the Web Modules portlet might fail due
to transfer or timeout problems, with the portlet returning to the initial state.
Scenario detail: When you deploy a portlet application Web module by clicking
the Install button in the Web Modules portlet, selecting a Web module from the
browse dialog and clicking Next, the portlet might return to the initial state as it
was before you clicked the Install button. No error message is displayed. In the
WebSphere Portal log file you might see an exception that says: Nested Exception
is org.apache.jetspeed.portlet.PortletException: Processing of
multipart/form-data request failed. Read timed out.
Cause: A timeout might have occurred on the HTTP connection when trying to
install the portlet application WAR file. This problem can depend on several
factors, for example:
v The size of the WAR file that you want to install.
v The bandwidth and load on your network.
v The timeout limits for several processes, for example the post size limit, the
connection input and output, the upload process, or the SOAP connection.
Solution: To resolve this problem, try changing one or more of the properties or
timeout values that can affect the installation of the WAR file. Here are some
examples:
v Increase the property PostSizeLimit in the plugin-cfg.xml property file of the
HTTP server.
52 Troubleshooting guide
v Set the property ConnectionIOTimeout. This property does not exist by default in
the WebSphere Application Server configuration. To add or set this property,
proceed by the following steps:
1. Open the WebSphere Application Server Administrative Console.
2. In the WebSphere Administrative Console, expand Servers.
3. Click Application Servers.
4. Click WebSphere_Portal.
5. In Container Settings, click Web Container Settings > Web container
transport chains.
6. Click on the appropriate host.
7. In Server Infrastructure, click Administration > Custom Properties.
8. If a property with the name ConnectionIOTimeout already exists, proceed
with the next step.
If a property with the name ConnectionIOTimeout does not exist, click New.
Add a new custom property with the name ConnectionIOTimeout and select
Seconds for the representation of the value.
9. Set the value. Use discretion when setting this value. The default is 5
seconds.
10. Save your changes to the configuration and restart WebSphere Application
Server.
Use discretion when changing these values. Depending on your portal
configuration and the size of the WAR file to be installed, it might be sufficient to
increase one parameter, or you might have to increase more than one parameter.
You might have to set one or more parameters to infinite.
Problem: Extracting a JNDI namespace in portal
WebSphere Application Server provides a command line utility for creating a JNDI
namespace extract of a dedicated application server. This utility is named
dumpNameSpace.sh, and is located in the WebSphere Application Server installation
directory app_server_root/bin.
To extract a namespace from a server, the following requirements must be met:
v The application server must be active.
v The target host name must be provided, if it is not extracted locally.
v The target port number must be provided, if it deviates from the default.
For a detailed list of parameters for the dumpNameSpace utility, call the utility with a
question mark as an input parameter. For example, change to the directory
app_server_root/bin, and enter dumpNameSpace.sh ?. If you run the utility without
any additional parameters, the namespace of the default application server of
WebSphere server1 is extracted, and the connection port 2809 is used.
Before you extract the JNDI namespace of the WebSphere Portal application server,
you need to determine the port number. To do this, open the WebSphere
Application Server Administrative Console and navigate to Servers > Application
Servers > yourPortalServerName > End Points > BOOTSTRAP_ADDRESS.
Chapter 1. Troubleshooting 53
To extract the JNDI namespace of WebSphere Portal on the local host for the port
number determined by the procedure above, change to the directory
app_server_root/bin and enter the following command, depending on your
operating system:
dumpNameSpace.sh -port port_number
where port_number is the port number that you looked up in the Administrative
Console.
The result is written to the standard output.
Problem: Error occurs when exporting files from various portlets
When you export files from the Manage Pages, Template Library or Policy
administrative portlets, you may receive one of the error messages below if using
Internet Explorer:
Manage Pages portlet:
<failure>com.ibm.wps.command.MissingParameterException: EJPEB0612E:
AbstractXmlExtractCommand Missing Parameter.</failure>
Template Library portlet: You will get an error message or message in browser
information bar
Policy portlet: XML document must have a top level element. Error
processing resource
Solution: Perform the following steps:
1. Open your Internet Explorer browser.
2. Click Tools > Internet Options.
3. Click the Security tab.
4. Click the Custom Level button.
5. Under the Downloads section, click the Enable radio button under Automatic
prompting for file downloads.
Problem: Error message EJPPH0004E on renamed wps.ear file
Portal shows the following message: EJPPH0004E: Administration rights for
Application Server are missing.
Cause: The portal EAR file wps.ear has been renamed.
Solution: Change the name of the file back to wps.ear. Do not rename the file. In
the administration console the portal must be shown as an enterprise application
with the name wps.ear.
Troubleshooting issues related to national language support
This section describes problems that can occur when viewing different languages
with WebSphere Portal.
Problem: Issues with browsers displaying DBCS characters in
selection boxes
This information concerns languages that use double-byte character sets (DBCS).
Sometimes when DBCS text is displayed in selection boxes (such as the selector for
54 Troubleshooting guide
pages), all of the characters are displayed as square boxes. It has not been possible
to determine the browser versions and operating systems on which this situation
occurs consistently.
Solution: None at this time.
Problem: Issues with information center and Portal Help search
If you use Microsoft Internet Explorer 6.x to display the WebSphere Portal
information center or Portal Help and then use the Search function, some
corrupted characters might be displayed in the search results list.
Solution: See the Requirements section in the information center to view a list of
other Web browsers that you can use.
Problem: Issues with Microsoft Internet Explorer in a Japanese
environment
Solution:
v If you access the portal in a Japanese environment with Microsoft Internet
Explorer, the backslash might be displayed when pushing the Japanese Yen key
in an input field of the portal. This is caused by Microsoft Internet Explorer in
UTF-8 encoding. To avoid this problem, use other browsers such as Netscape or
Mozilla, or change the character set of the portal from UTF-8 to Shift_JIS. Refer
to Changing the character set for a language.
v The Rich Text Component of WebSphere Portal Productivity Components allows
you to change a normal format to a heading format, and vice versa. This might
be not available if you access the portal in a Japanese environment with
Microsoft Internet Explorer. To avoid this problem, use other browsers such as
Mozilla.
Problem: Message corruption for Japanese locale in Portal
Scripting Interface with interactive mode
When use Portal Scripting Interface with interactive mode (wpscript.sh under
portal_server_root/bin directory), Japanese messages might appear corrupt.
Solution:
1. Use the following commands:
chcp -a IBM-943C -e IBM-1399
2. Change encoding in wsadmin.sh under app_server_root/bin directory to the
following:
EXTRA_D_ARGS="-Dfile.encoding=cp943c $DELIM -Djava.ext.dirs="$JAVA_EXT_DIRS""
Problem: Message corruption for Japanese locale in
ConfigTrace.log
When running portal configuration jobs with a Japanese locale, Japanese messages
might appear corrupt in the log file portal_server_root/log/ConfigTrace.log.
Solution:
Apply the APAR PK33442 of WebSphere Application Server.
Chapter 1. Troubleshooting 55
Be sure to confirm that the encoding in WPSconfig.sh in portal_server_root/config is as follows:
EXTRA="-Xnoargsconversion -Dfile.encoding=Cp943C"
Problem: Search Crawler OutofMemory error
You might receive an OutofMemory error when using Search Crawler on large
portlet JSPs.
Solution: Either pre-compile your large portlet before using Search Crawler or see
Setting the JVM max heap size to increase your JVM heap size.
Troubleshooting the XML configuration interface
The topic gives administrators information to assist them with preventing,
identifying, and correcting possible problems that might occur when using the
XML configuration interface.
v “Problem: Unexpected syntax errors” on page 57
v “Problem: Message ″XMLC0091E: The servletref attribute is required to create a
portlet clone . . . ″” on page 57
v “Problem: Message "XMLC0049E: Input syntax error ...", followed by
"org.xml.sax.SAXParseException: cvc-elt.1: Cannot find the declaration of
element ’request’."” on page 57
v “Problem: Message ″LDAP: error code 49 - Invalid Credentials″ is misleading”
on page 57
v “Problem: User data not exported as specified” on page 58
v “Problem: Message″XMLC0142E: Unique name unique_name is already used in
the portal.″” on page 58
v “Problem: XML configuration interface tasks result in errors when using HTTP
server port” on page 58
v “Problem: Cannot use the XML configuration interface if it is externalized in
security” on page 58
v “Problem: Re-creating and browsing a page can result in a duplicate key error”
on page 59
v “Problem: XML import might fail with out-of-memory error” on page 59
v “Problem: WPSconfig command fails when running XML configuration
interface” on page 60
v “Problems when exporting or importing policies by using the XML configuration
interface” on page 60
v “Problems when transferring Document Manager” on page 61
v “Portlet global state attribute without wire is not exported by XML export” on
page 61
v “You cannot delete attributes by using the XML configuration interface” on page
61
v “User and Group import via the XML configuration interface” on page 62
v “ReleaseBuilder ignores deletion of attributes” on page 62
v “Global settings cannot be set in a cluster by using the XML configuration
interface” on page 63
56 Troubleshooting guide
Problem: Unexpected syntax errors
Although the XML input file seems to be valid, inexplicable syntax errors are
reported, for example unclosed XML tags.
Solution: A possible reason is that your files are being truncated before they are
processed by the portal. This can typically occur for the following reasons:
1. Your input file contains invalid UTF-8 characters. A good way to check your
input files is to view them with Microsoft Internet Explorer. Microsoft Internet
Explorer shows errors if your input contains invalid characters.
2. You have a problem with your HTTP communication setup, for example, your
input is relayed through a HTTP server that truncates it. In this case you can
check for communication problems by specifying the -echo command line
parameter when you call the XML configuration interface tool. When this
parameter is specified, your request is not processed, but simply returned as it
is read by the server. If the output is different from your input file, your
request was modified somewhere along the communication path.
Problem: Message ″XMLC0091E: The servletref attribute is
required to create a portlet clone . . . ″
The attempt to deploy a portlet in a XML request results in the error message
given above.
Solution: There is a mismatch between the name, uid and refid attributes that are
given in the XML request and those that were specified in the portlet.xml
deployment descriptor for your portlet or portlet application. Therefore XML
processing tries to create new portlets where it should only update those that have
been created as part of the WAR file deployment. Use the Install portlet to deploy
your WAR file, export the portlet application (package), and compare the export
with your XML request, or compare your XML request with the portlet.xml. Make
sure that the names and IDs for portlets and portlet applications are identical.
Problem: Message ″XMLC0049E: Input syntax error ...″, followed
by ″org.xml.sax.SAXParseException: cvc-elt.1: Cannot find the
declaration of element ’request’.″
The attempt to import an XML file results in the error messages given above.
Solution: Your XML file contains an invalid schema or namespace declaration.
Check the request element for typographical errors or missing attributes. The
request must have the following form:
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
...>
Problem: Message ″LDAP: error code 49 - Invalid Credentials″ is
misleading
If you try to connect to the portal with security and LDAP enabled, but if the
LDAP server is not available, the following error message is returned in the XML
response file:
com.ibm.websphere.wmm.exception.WMMSystemException:
The following Naming Exception occurred during processing:
"javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials]".
Chapter 1. Troubleshooting 57
This message can be misleading.
Solution: The LDAP error message Invalid Credentials means that the user name
or password are wrong. It can also mean that the LDAP server is not available at
all.
Problem: User data not exported as specified
User name data are not exported as specified by the user tag attributes firstname,
lastname, or name. The reason is that the values of some attributes of the tag user
correspond to settings in included parameter tags. If you include both in your
export request, but specify different values for them, then the value set by the
parameter tag overwrites the value set by the attribute, and is exported as the
attribute.
Solution: Use only one of the two ways to specify the user data, either the
attribute or the parameter tag. For more information about this, see the description
of the user tag under XML reference, Types of portal resources.
Problem: Message″XMLC0142E: Unique name unique_name is
already used in the portal.″
One or more nested elements were not created properly.
Solution: When you create a nested element, for example a component, with a
uniquename attribute, the whole hierarchy upward from that element must also
have uniquename attributes. Example XML export request snippet:
<content-node ...
<component uniquename="component_1"...
<component uniquename"component_2"...
<component uniquename"component_3"...
. . . . .
</component>
</component>
</component>
</content-node>
Problem: XML configuration interface tasks result in errors when
using HTTP server port
XML configuration interface tasks may result in errors if you do not use the direct
port.
Solution: When you process tasks using the XML configuration interface, use the
direct port, for example, 10038, rather than going through the HTTP server on port
80.
Problem: Cannot use the XML configuration interface if it is
externalized in security
If the virtual resource XML_ACCESS that represents access to the XML configuration
interface is put under protection of an external security manager, you can no
longer use the XML configuration interface.
Solution: If the access rights of WebSphere Portal are externalized to an external
security manager, such as Tivoli Access Manager, make sure that the XML
configuration interface virtual resource is not externalized.
58 Troubleshooting guide
Problem: Re-creating and browsing a page can result in a
duplicate key error
If you delete a page with an object ID and use the XML configuration interface to
re-create the same page with the same object ID, you might receive an error
message indicating the operation was aborted because it would have caused a
duplicate key value.
Example scenario: You delete a page with an object ID. You use an XML import
request to re-create the same page with the same object ID. The import fails with
the following message: The statement was aborted because it would have caused
a duplicate key value in a unique or primary key constraint.
Cause: When you delete a page, the portal marks the page for deletion but does
not actually delete the page until a later point in time when the scheduled cleanup
service runs. Until that time remainders of the deleted page exist in the portal.
They can interfere with adding the new page.
Solution: To avoid this, run the cleanup service task before re-creating the page
with the XML configuration interface. After you have deleted a page with an object
ID, do not re-create the same page with the same object ID without first running
the cleanup service task. As an alternative, you can configure the cleanup service
for immediate deletion. This deletes portal pages immediately as you run the
cleanup task. For more details about how you can use the XML configuration
interface to perform a cleanup refer to the XML reference under the task tag. For
more details about the cleanup service and how to configure it, refer to Delayed
cleanup of deleted portal pages.
Note: When you run the XML cleanup task, the XML configuration interface only
schedules the task to be run in WebSphere Application Server and returns.
This does not necessarily mean that IBM WebSphere Application Server runs
the task immediately. To determine when a task started and ended, check
the portal log wps_date_time.log for the EJPDE0002I and JPDE0003I
messages. These messages confirm that the cleanup task has successfully
completed.
Alternate solution option: Another possible option for solution is to set the
attribute create-oid=″true″ for the request tag in your input script. This creates
new object IDs for all updated items. The original items remain unchanged.
Problem: XML import might fail with out-of-memory error
An XML import of portal resources might fail with an OutOfMemoryError.
Cause: This error results from a limited heap size.
Solution: Proceed by the following steps:
Follow these steps to set the JVM max heap size limit:
1. Open the Administrative Console of WebSphere Application Server.
2. Navigate to Servers → Application Servers → yourPortalServerName → Java and
Process Management → Process Definition → Servant → Java Virtual Machine →
Maximum Heap Size.
3. Determine the configured maximum heap size, for example, this might be 512
MB.
Chapter 1. Troubleshooting 59
4. Increase the maximum heap size, for example to 768 MB maximum.
5. Ensure that the system has enough physical memory for all of the processes to
fit into physical memory, plus enough for the operating system.
Notes:
v When more memory is allocated than the physical memory in the
system, paging will occur, and this can result in very poor
performance.6. Restart your portal.
7. Run the XML import script again. The OutOfMemoryError should disappear.
WebSphere Portal runs with an 31 bit JVM. Therefore, the address space limit is 2
GB. The JVM heap size should be set to 768 MB maximum because WebSphere
Portal also fits into the same address space. You can find more information at Java
virtual machine storage tuning tips for z/OS. Also refer to Tuning performance.
Problem: WPSconfig command fails when running XML
configuration interface
Occasionally you might encounter an error where the WPSconfig command fails
because of a problem running the XML configuration interface.
Cause: Typically this error results from a problem with the host name and port
number configuration in WebSphere Application Server that prevents proper
operation of the xmlaccess command.
For example, the error message below resulted from an attempt to access an SSO
domain that could not be resolved by localhost:
SRVE0017W: A WebGroup/Virtual Host to handle localhost:10038 has not been defined.
Solution: To correct this problem, edit the wpconfig.properties file and update the
value of the XmlAccessHost property with the full host name of the portal server.
Problems when exporting or importing policies by using the XML
configuration interface
Problem: When you use the XML configuration interface to work with policies, the
following limitations apply:
1. The policy-sub-nodes are stored in a separate file. This file can be referenced by
an XML script, and that link can be exported and imported by using the XML
configuration interface.
2. Access control for policies is exported only for the base policy-node, but not for
the sub-nodes.
3. The portal ReleaseBuilder does not handle policies.
Cause: This is a known limitation.
Solution: To resolve this limitation, you need to add some manual steps to running
the XML export and imports:
1. After successful export of the policies, copy the separate file that contains the
policy-sub-nodes from the source to the target system.
2. Optional: If you copied that file to a different directory location, adapt the path
given for the separate file with the policy-sub-nodes in the XML export result
file.
60 Troubleshooting guide
3. After successful import of the policies, configure access control permissions on
the sub-nodes manually by using the Resource Permissions portlet.
Problems when transferring Document Manager
Problem: When you use the XML configuration interface to transfer a portal
configuration that includes the Document Manager application, buttons might be
missing from the user interface panels of that application.
Cause: This is a known limitation.
Solution: To resolve this limitation, you need to add some additional steps after
performing the transfer by using the XML configuration interface:
1. Log in to the WebSphere Application Server Administrative Console.
2. Select the Document Manager application. To do this, proceed as follows:
a. Expand Applications.
b. Select Enterprise Applications.
c. Locate the application that starts with ″Document Manager″.3. Click Map Security Roles to Users/Groups.
4. Assign the Authenticated role to everyone.
5. Save your changes.
Portlet global state attribute without wire is not exported by XML
export
Problem: If you export a portlet that has the global state attribute set, but no
wires, the global attribute is not exported. Consequently, this attribute is missing
after re-import of the XML script.
Cause: The XML configuration interface does not export the global state attribute
of portlets.
Solution: To resolve this limitation, use one of the following options:
1. After the XML import, reset the portlet to global state by using the portal
administrative user interface. Select Edit page layout → Wires → Manage
Actions and set the portlet to global state.
2. Before the XML export, create a wire for the portlet. The XML configuration
interface exports the wire. The XML import creates the global attribute for all
portlets that have a wire.
You cannot delete attributes by using the XML configuration
interface
Problem: You cannot delete the value for an attribute by using the XML
configuration interface.
Cause: This is a known limitation. The XML configuration interface does not allow
deletion of attributes.
Solution: You can overwrite the value of the attribute by another value by using
the XML configuration interface.
Refer also to “ReleaseBuilder ignores deletion of attributes” on page 62.
Chapter 1. Troubleshooting 61
User and Group import via the XML configuration interface
Problem: The XML configuration interface is not intended to perform the import
or migration of large user and group populations.
Cause: This is a known limitation. The XML configuration interface does not allow
import of large user groups.
Solution: To migrate or transfer large user groups, use tools provided by your
LDAP vendor. If you want to import the Access Control on users and groups, you
have to only import the group tag without nested member-user or member-group
tags. Modify the XML script accordingly. You can also export groups without the
members by setting the attribute export-user of the request tag to the value
no-member.
ReleaseBuilder ignores deletion of attributes
Problem: If you delete values of fields in the portal administrative user interface,
this might result in empty attributes in an XML export file. If you then use
ReleaseBuilder to extract the changes between the configurations before and after
the deletion of attributes, the difference file does not reflect the deletion of the
attributes.
Cause: This is a known limitation. The ReleaseBuilder does not recognize the
deletion of attributes. Refer also to “You cannot delete attributes by using the XML
configuration interface” on page 61.
Solution: After you have completed the staging process with ReleaseBuilder, delete
the attributes on the target portal system by using the same steps as you
performed on your source system.
Sample scenario and files: An example scenario and sample scripts are given in
the following.
1. You create configuration status export1 of your source portal by using the XML
configuration interface.
2. You modify your source portal by deleting the contents of fields in the portal
administrative user interface that lead to attributes without a value in an XML
export file.
3. You create configuration status export2 of your source portal by using the XML
configuration interface.
4. You use ReleaseBuilder to extract the changes between export1 and export2.
The resulting differential file does not contain the deleted attributes.
Sample XML script file snippet export1:
<client action="update" domain="rel" manufacturer="dilbert" markup="html" markup-version="1.1"
name="puppy" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="250" version="1.0">
<useragent-pattern>dogert</useragent-pattern>
<client-capability update="set">dish</client-capability>
<client-capability update="set">html</client-capability>
</client>
Sample XML script file snippet export2:
62 Troubleshooting guide
<client action="update" domain="rel" manufacturer="dilbert" markup="html" markup-version="1.1"
name="" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="287" version="">
<useragent-pattern>dogert</useragent-pattern>
<client-capability update="set">dish</client-capability>
<client-capability update="set">html</client-capability>
</client>
From the two exports above, ReleaseBuilder generates the following differential
file:
<?xml version="1.0" encoding="UTF-8"?>
<!-- IBM WebSphere Portal/6.0 build wp600_154 exported on Wed Apr 05 14:24:19
EDT 2006 from xyz -->
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" build="wp600_154" type="update"
version="6.0.0.0" xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">
<portal action="locate">
<client action="update" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="287"/>
</portal>
</request>
If you use this ReleaseBuilder differential file to update your target portal, the
name and version attributes of the client tag are not deleted on the target portal.
To complete the update, you have to delete the attributes manually by using the
same steps by which you deleted the attributes on the source portal.
Global settings cannot be set in a cluster by using the XML
configuration interface
Problem: The XML configuration interface fails with the following error when you
try to set global settings in a clustered environment.
<status element="[global-settings]" result="failed">
<message id="EJPXA0043E">com.ibm.wps.command.xml.XmlCommandException:
EJPXA0043E: An error occurred while creating or updating the resource.
[global-settings]</message>
<message id="EJPEB0002E">com.ibm.wps.command.CommandException:
EJPEB0002E: An exception occurred.</message>
<message>java.security.PrivilegedActionException: java.lang.NullPointerException</message>
</status>
Cause: The global settings are stored in the WebSphere Application Server (WAS).
For changes to the global settings a WAS API call is invoked. During this call the
following exception is thrown in the clustered environment:
Caused by: java.lang.NullPointerException
at at com.ibm.wps.services.ServiceHelper$4.run(Unknown Source)
at at com.ibm.ws.security.auth.distContextManagerImpl.runAs(distContextManagerImpl.java:2782)
... 43 more
Solution: To configure these settings, configure them directly in the administrative
console, as described in Setting configuration properties.
Troubleshooting business process integration
Problem: After staff resolution has been changed in the process
model and the process been redeployed, no changes can be
recognized
This problem can occur when the staff query has not been updated.
Solution: Force an update of the staff resolution by executing the following
command:
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
Chapter 1. Troubleshooting 63
The following describes the usage of this script in more detail:
Usage:
wsadmin -f refreshStaffQuery.jacl
[ ([-node nodeName] -server serverName) | (-cluster clusterName) ]
[ -template process template name | -userlist username{,username} ]
The script refreshes staff query entries of a process template after the underlying
staff directory has been changed. If no arguments are specified, the staff queries for
all processes are refreshed. You can apply changes on the server serverName, on the
node nodeName, or on the cluster clusterName.
Problem: The staff resolution is not working
This problem can manifest itself in the My Tasks portlet if the task list is not
showing the correct tasks for the user. This problem can occur from one of the
following possible causes:
v Wrong security settings, possibly in LDAP. For more information, see
Configuring security.
v Wrong verb settings or incorrect name/value pairs for a staff activity or the
input (receive) node, as described under the Security settings in Enabling the
business process for portal. The process designer should check the settings for
the process in Application Developer Integration Edition.
v Wrong JNDI name for the staff plugin specified, as described in Configuring the
business process container for the portal.
v No Potential Owner is defined for the input node as described under the
Security settings in Enabling the business process for portal. The process
designer should check the settings for the process in Application Developer
Integration Edition.
Solution: After checking and correcting these settings, force an update of the staff
resolution by executing the following command:
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
Problem: The LDAP system has been changed and staff
resolution is not performed correctly anymore
This problem can occur from one of the following possible causes:
v Wrong filter settings in WebSphere Application Server.
v The security settings in the business process need to be updated with the LDAP
changes.
v Wrong verb settings for the staff activity in the business process. This could be
the search attribute changed from uid to cn or vice versa.
Solution: After checking and correcting these settings, force an update of the staff
resolution by executing the following command:
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
64 Troubleshooting guide
Problem: The process template is not available
This problem can occur from one of the following possible causes:
v The process EAR has not been installed correctly.
v The process EAR has not been started.
Solution: After checking and correcting these settings, force an update of the staff
resolution by executing the following command:
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
Problem: The process cannot be deployed/started
This problem can occur from one of the following possible causes:
v The process EAR file does not contain the right relational database (RDB)
mappings as described under Database support in Enabling the business process
for portal.
v During database creation for the business process container, tables have been
created within a different schema as the database user specified in
bpeconfig.properties. Check the settings in bpeconfig.properties and run the
ddl scripts described in Configuring the business process container for portal.
Solution: After checking and correcting these settings, force an update of the staff
resolution by executing the following command:
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
Problem: After the process has been initiated it jumps to the
FAILED state
This problem can occur from one of the following possible causes:
v Wrong security settings in the process EAR.
v Wrong verb settings or verb JNDI specification for the staff activity in the
process model.
Solution: After checking and correcting these settings, force an update of the staff
resolution by executing the following command:
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
Problem: UnexpectedFailureException is thrown during process
initialization
This problem can occur from one of the following possible causes:
v Wrong security settings in the process EAR.
v Wrong verb settings or verb JNDI specification for the staff activity in the
process model.
Solution: After checking and correcting these settings, force an update of the staff
resolution by executing the following command:
Chapter 1. Troubleshooting 65
refreshStaffQuery.jacl -server server1 -template templatename
The script is located at was_root/ProcessChoreographer/util.
Troubleshooting Workflow for composite applications
This section contains information that can assist you in preventing, identifying, and
correcting problems related to Workflow for composite applications.
Upgrading Workflow configuration
Refer to this section when troubleshooting problems related to upgrading an
existing configuration of Workflow.
Upgrading Workflow configuration fails.
If you encounter upgrade failures, download and apply interim fix
6.0.2.0-WS-WBI-IFIY94772.pak available at the IBM WebSphere Portal
Enable for z/OS Support site given as a Related Reference. Do not apply
this interim fix before you upgrade your Workflow configuration. This
interim fix must be applied after you encounter an upgrade failure.
Edit Workflow Template is not available or does not work.
After you upgrade Workflow configuration, if application template menus
do not display Edit Template Workflow or clicking Edit Template
Workflow does not display the Workflow Builder portlet, download and
apply interim fix 6.0.2.0-WS-WBI-IFIY93684.pak available at available at the
IBM WebSphere Portal Enable for z/OS Support site given as a Related
Reference.
Troubleshooting Lotus Domino and the Extended Products
Refer to this topic for problems with the Domino and Extended Products servers.
v Setting debug parameters for the Extended Products
v Troubleshooting IBM Lotus Domino
– “Problem: WebSphere Global Security with SSO-enabled Lotus Domino LDAP
requires modification to the Lotus Domino Web Configuration document ” on
page 67
– “Problem: SSO does not work after the portal is configured to use SSL ” on
page 67
– “Problem: Single Sign-On may fail when the portal is configured to use
multiple realms” on page 68
– “Problem: Database lists in some portlets fail to populate with database
names” on page 68
– “Problem: The Domino Directory used for people awareness may cause
delays or lack of awareness if it contains identical common user names” on
page 69
– Problem: For portlets that display users’ names with online awareness, similar
names do not display the correct online status
– “Problem: For portlets that display users’ names with online awareness,
names containing commas do not display the correct online status when the
Lotus Domino server is 6.5.4” on page 70v Troubleshooting IBM Lotus QuickPlace
– “Problem: Team Workplace 6.5.1 (Lotus QuickPlace) requires an interim fix to
work with Lotus Domino 6.5.x” on page 70
– Enabling diagnostic tracing on the Lotus QuickPlace (QuickPlace) server
66 Troubleshooting guide
Setting debug parameters for the Domino Extended Products
You can set the following parameters in the NOTES.INI file of the two Domino
servers running Lotus Sametime and Lotus QuickPlace:
debug_sso_trace_level=2
debug_outfile=debug.out
Tip: Name the Lotus Sametime debug file imdebug.out and Lotus QuickPlace file
twdebug.out to distinguish between the two.
You can add these through the Domino console by typing: set config <parameter>
or by editing the NOTES.INI file manually.
Restart the server to create the new debug out file in the domino_data/IBM_TECHNICAL_SUPPORT directory.
Troubleshooting IBM Lotus Domino
This section provides information about troubleshooting problems that might arise
with Lotus Domino.
Problem: WebSphere Global Security with SSO-enabled Lotus
Domino LDAP requires modification to the Lotus Domino Web
Configuration document
If you enable single sign-on (SSO) between WebSphere Application Server and
Lotus Domino servers in a portal environment that has applied WebSphere Global
Security, you will need to edit the Lotus Domino Web Configuration document to
correct an error that occurs in the LDAP Realm when Lotus Domino imports LTPA
keys from WebSphere Application Server.
Solution: To correct the LDAP Server setting that is imported into Lotus Domino
with the LTPA keys, open the Lotus Domino Web Configuration document and
edit the LDAP Server value to include the backslash, for example,
yourLDAPServer.yourdomain.com\:389. Restart the Lotus Domino LDAP server to
initialize this change. Replicate the Domino Directory to all Lotus Domino LDAP
servers, Lotus Sametime, andLotus QuickPlace servers. Remember to start and stop
the HTTP task on all Lotus Domino and Lotus QuickPlace servers.
Problem: SSO does not work after the portal is configured to use
SSL
If you configure SSO for WebSphere Application Server and Lotus Domino servers
in a portal environment, and then enable SSL for the portal, you must regenerate
and then import a new LTPA key to reflect the new port number for the SSL
configuration.
Solution: If you enable SSO between WebSphere Application Server and Lotus
Domino servers, the default port number used is 389. This port number changes to
636 (by default) for an SSL configuration. In the WebSphere Administrative
Console, you must regenerate the LTPA key, restart WebSphere Application Server,
and then export the key from the WebSphere Administrative Console. Next, import
the LTPA key into the Web SSO Configuration document on the Lotus Domino
servers.
Chapter 1. Troubleshooting 67
Problem: Single Sign-On may fail when the portal is configured
to use multiple realms
Single Sign-On (SSO) may work incorrectly on Lotus Domino, Lotus Sametime, or
Lotus QuickPlace servers integrated in the site if WebSphere Portal is configured
with multiple realms. Features that may fail include user authentication in
collaborative portlets, Lotus Sametime awareness, and automatic detection of mail
files for Lotus Domino messaging portlets.
When the portal is configured for multiple realms (using the relevant configuration
topics in the Information center under Database user registry overview or LDAP user
registry), the security realm is set to the value WMMRealm. This value cannot be
recognized by the Domino and Extended Products servers.
Solution: Before retrieving the LPTA token and copying it to Domino and
Extended Products servers to include them in SSO, make sure that the security
realm has been corrected in configuration properties to an alias for the LDAP user
registry. Perform the following steps to set the userRegistryRealm property on the
WebSphere Application Server:
1. In the WebSphere Application Server Administrative Console, select
Security>Global Security>User Registry>Custom>Custom Properties.
Note: See Starting and logging off the administrative console for information
on how to log on to the WebSphere Application Server Administrative
Console.
2. Add the userRegistryRealm key with the value yourname, where this is the
name of the security realm used within the WebSphere Application Server cell
to uniquely identify the user based on their origin source. For example, the
LDAP implementation of WebSphere Application Server uses the LDAP server
name and the used port as the origin source, such as
ldap.nameofyourcompany.com:389.
3. Save your changes.
If SSO has already been configured for Lotus Domino servers, you can still correct
the problem by setting the property above, and by correcting the value in the
security.xml file for any additional exports of the LTPA token. For instructions,
see the following technote:
Technote 1198736: Single-Sign-On issues between WebSphere Portal and other
applications (e.g. Lotus Domino or Sametime) within the same Single-Sign-On
domain
Problem: Database lists in some portlets fail to populate with
database names
In the Lotus Notes View, Domino Web Access, and My Lotus QuickPlaces portlets,
drop-down lists of database names may appear empty. There are several possible
causes:
v The Lotus Domino server configured for use with the portal does not have SSL
set up correctly
v The Lotus Domino server uses the setting Redirect to SSL instead of Enable
SSL.
v The Lotus Domino messaging/application server for the portlets does not
actually contain databases of the correct type.
68 Troubleshooting guide
v All Lotus Domino servers used with the portal do not have SSL certificates
signed by the same certificate authority.
Solution: Perform the following steps to eliminate the possible problems:
1. Ensure that the Lotus Domino server configured for use with the portal has
SSL set up properly.
2. Do one of the following:
v If the Lotus Domino server uses HTTP, set HTTP to run on the default port
of 80.
v If the Lotus Domino server uses HTTPS, set HTTPS to run on the default
port of 443, and enable DIIOP over SSL. 3. In the Server document, select Internet Protocols → HTTP, and make sure that
Allow HTTP clients to browse databases is set to Yes.
4. While examining the Lotus Domino server, determine whether the server uses
the Enable SSL or Redirect to SSL setting.
5. Restart the Domino server.
6. If the problem remains, check the Lotus Domino messaging/application
servers and make sure that the databases users are attempting to view
through the portlets exist, and are of the appropriate design for the
portletType parameter configured in the portlets. For example, in a portlet
configured with a portletType of NOTESDISCUSSION, the drop-down list
shows only Notes databases with a discussion design. If no databases of the
appropriate type exist, either inform users of this error, or make appropriate
databases available.
7. If the problem remains, examine the SSL certificates for each of the Lotus
Domino servers that contain source databases for portlets in the portal, and
make sure they are all signed by a single certificate authority (CA).
8. From any of the Lotus Domino servers that has a properly signed SSL
certificate, copy the TrustedCerts.class file from within the
domino_data_root/domino/java directory.
9. Navigate to the portal server’s class directory portal_server_root/shared/app/ and paste the copied TrustedCerts.class file.
10. If the problem remains, and you determined earlier that the Lotus Domino
server uses the Redirect to SSL setting, locate and edit the
CSEnvironment.properties file on the portal server.
11. If the following property does not already exist and is not already set to this
value, add it and set its value using the following line:
CS_SERVER_DOMINO_DIRECTORY_1.iiopport=63148
12. Save the CSEnvironment.properties file.
13. Restart the portal server.
Problem: The Domino Directory used for people awareness may
cause delays or lack of awareness if it contains identical
common user names
Solution: Modify names of any users who share a common name so that names
become unique (for example, by including an initial).
Chapter 1. Troubleshooting 69
Problem: For portlets that display users’ names with online
awareness, similar names do not display the correct online
status
If two users’ names are similar – for example, they begin with identical strings,
such as Jane Smith and Jane Smithson – and the LDAP directory configured for the
portal is not Lotus Domino, the correct online status for the users will not be
displayed. This problem occurs in any of the Domino and Extended Products
Portlets that display names with online awareness.
Solution: Add the following content to the CSEnvironment.properties file:
# The format of the name that will be added to the watch lists for awareness.
CS_SERVER_SAMETIME_1.watchnameformat=dn
Problem: For portlets that display users’ names with online
awareness, names containing commas do not display the correct
online status when the Lotus Domino server is 6.5.4
If a user’s common name contains a comma, for example, ″Smith, Chris,″ and the
Lotus Domino LDAP server is running release 6.5.4, the correct online status for
the user will not be displayed in the portlet. This problem occurs in any of the
Domino and Extended Products Portlets that display user’ names with online
awareness.
Workaround: There is a workaround that will fix the problem. However, if the
portal also uses Lotus Domino for its LDAP directory, this workaround will disable
awareness for the People Finder portlet entirely, even on names that do not contain
commas.
Add the following content to the CSEnvironment.properties file:
# The format of the name that will be added to the watch lists for awareness.
CS_SERVER_SAMETIME_1.watchnameformat=dn
Solution: Upgrade the LDAP server to a later release of Lotus Domino. If you
cannot upgrade at this time, check with IBM Support for an interim fix for the
Lotus Domino LDAP server release 6.5.4.
Troubleshooting IBM Lotus QuickPlace
This section provides information about troubleshooting problems that might arise
with Lotus QuickPlace.
Problem: Team Workplace 6.5.1 (Lotus QuickPlace) requires an
interim fix to work with Lotus Domino 6.5.x
Without this fix, Lotus Domino HTTP does not start, preventing the Team
Workplace (Lotus QuickPlace) server software from operating.
Note: For release 6.5.1 only, Lotus QuickPlace is called Team Workplace.
Solution: A required interim fix for Team Workplace release 6.5.1 is available on
the IBM Support Web site. Refer to the following troubleshooting technote:
Technote 1198555: Required Team Workplace 6.5.1 Enabling Fixes for Domino
6.5.4 and 6.5.5
70 Troubleshooting guide
Enabling diagnostic tracing on the Lotus QuickPlace
(QuickPlace) server
Perform the following steps to enable diagnostic tracing on the Lotus QuickPlace
(QuickPlace) Server Console (when using any QuickPlace portlet, or any other
portlet using the QPService APIs):
1. Add the following lines in the notes.ini file of the Lotus QuickPlace server.
v For Information: QuickPlaceJavaLogging=3
v Details for other logging levels:
– For Debug: QuickPlaceJavaLogging=5 or 4
– For Error only: QuickPlaceJavaLogging=0 or 1
– For Warnings: QuickPlaceJavaLogging=2
2. Restart the Lotus QuickPlace server.
Troubleshooting Domino and Extended Products Portlets
Refer to this topic for problems with the Domino and Extended Products Portlets
This section includes tips for troubleshooting the configuration of Domino and
Extended Products Portlets.
Note: Other troubleshooting information on the Domino and Extended Products
Portlets can be found in the Known limitations for Collaboration features section
of the Release Notes for your current release of IBM WebSphere Portal
Enable for z/OS.
v “Enabling logging”
v “Parameters to enter for logging specific components” on page 72
v “Collaborative portlet problems” on page 72
v “People Finder portlet, people awareness, and Person menu problems” on page
74
v “My Lotus QuickPlaces portlet problems” on page 78
v “Lotus Web Conferencing portlet problems” on page 81
v “Who Is Here portlet problems” on page 85
v “Sametime Contact List portlet problems” on page 85
v “Lotus Notes View portlet problems” on page 85
v “Domino Web Access portlet problems” on page 88
v “Domino Document Manager portlet problems” on page 89
Enabling logging
In many cases you can help troubleshoot portlet problems by enabling logging.
You can specify logging in the administrative console on the IBM WebSphere
Application Server that supports WebSphere Portal.
You can specify parameters to log:
v Lotus Collaborative Services operations
v the People Finder portlet and Member Manager
v other collaborative portlets
v the operation of the Person tag and Person menu
Perform the following steps to enable logging.
Chapter 1. Troubleshooting 71
1. Open the administrative console by entering this URL in your browser:
http://yourPortalServer.yourDomain.com:your_port/ibm/console
2. Log in as an administrator.
3. Select Troubleshooting --> Logs and Trace
4. In the Server column in the table, click the WebSphere_Portal link, then click
Diagnostic Trace in the next table that appears.
5. On the Configuration tab, under General Properties, in the Enable Trace row
of the table, make sure the check box ″Enable trace with the following
specification″ is selected.
6. In the text box in the Trace Specification row, type or paste the parameters you
want to use, separating them with a colon. Refer to the table Parameters to
enter for logging specific components.
For example, the following parameter logs all Collaborative Services operations.
com.lotus.cs.*=all=enabled
7. Click Apply, then Close.
8. Back in the administrative console, click Apply, Save, and then Save again to
save changes to the Master Configuration.
9. Restart the portal server.
The resulting traces will be written to the following file:
portal_server_root/log/trace.log
Parameters to enter for logging specific components
Components logged Parameter string
Awareness (Collaborative Services) and collaborative
portlets other than People Finder
com.lotus.cs.*=all=enabled
People Finder and Member Manager com.ibm.websphere.wmm.*=all=enabled:com.ibm.ws.wmm.*=all=enabled:WSMM=all=enabled:com.ibm.wps.peoplefinder.*=all=enabled
Person tag and Person menu com.ibm.wkplc.people.portal.*=all=enabled:com.ibm.workplace.people.portal.*=all=enabled
Collaborative portlet problems
This section lists problems common to all or most Domino and Extended Products
Portlets or collaborative portlets.
Problem: Collaborative portlets require additional configuration for
compatibility with Tivoli Access Manager
Many features of the collaborative portlets will not work if IBM Tivoli
Access Manager for e-business protection in your site is not properly
configured. Problems include failure of awareness, failure of the Lotus
Sametime server to authenticate with the Lotus Web Conferencing portlet,
and failure of the My Lotus QuickPlaces portlet to connect to the Lotus
QuickPlace server.
Solution: An interim fix is available on the IBM Support web site. Refer to
the following troubleshooting technote:
72 Troubleshooting guide
Technote 1191185: Awareness, Connection and Authentication
Problems if Collaborative Portlets v5.1 not Configured for Tivoli
Access Manager
Problem: Collaborative portlets require an interim fix to STlinks applet to work
in Mozilla
In the Mozilla browser, many problems in collaborative portlets result from
the version of the STlinks applet configured on the Lotus Sametime server,
as well as versions of other related files.
For example, a timing problem prevents the Who Is Here and Lotus Web
Conferencing portlets from working if deployed on the same portal page,
awareness may fail, the Chat button in the Domino Web Access portlet
may not work, and the Who Is Here portlet may be unable to display the
membership list.
Solution: An interim fix for the STlinks applet is available on the IBM
Support Web site. Corrected files are available to solve the problems above.
Refer to the following troubleshooting technote:
Technote 1191188: Lotus Collaborative Portlets v5.1 Exhibit Problems
when Accessed via Mozilla Browser
Problem: Distinguished names containing escape characters cause people
awareness to function incorrectly in several Domino and Extended Products
Portlets
Portlets with this problem include Lotus Web Conferencing, My Lotus
QuickPlaces, and Sametime Contact List.
Solution: An interim fix is available on the IBM Support Web site. Read
the following technote:
Technote 1191190: People Awareness in v5.1 of Lotus Collaboration
Center Portlets Does not Function Properly
Problem: SSO for Domino and Extended Products fails for users containing
LDAP special characters in their distinguished names
LDAP special characters existing in distinguished names of either users or
groups prevent SSO from working correctly between the portal, Lotus
Sametime, Lotus QuickPlace, and Lotus Domino databases unless
configuration fixes are applied to the servers. For example, a user whose
name contains special characters may be asked to authenticate with Mail,
Calendar, or Address book instances of the Domino and Extended Products
Portlets.
The LDAP special characters are:
v A space or ″#″ character occurring at the beginning of the string
v A space character occurring at the end of the string
v One of the characters ″,″, ″+″, ″″″, ″\″, ″<″, ″>″ or ″;″
Also, the ″/″ and ″@″ are Lotus Domino special characters, and will cause
the same problems without the interim fixes available from IBM Support.
Solution: Interim fixes for releases 6.5.1 IF1 and 6.5.3 are available on the
IBM Support Web site. Refer to the following troubleshooting technote:
Chapter 1. Troubleshooting 73
Technote 1191194: SSO for Domino and Extended Products Fails for
Users Containing LDAP Special Characters in their Distinguished
Names
Problem: Dates are not always in the correct format for some locales
In portlets such as Lotus Web Conferencing that display dates, dates may
sometimes appear formatted as mm/dd/yy when they should be
displayed as dd/mm/yyyy.
Solution: Edit the language.properties file, add lines similar to the
following for any languages that are not displaying the desired format,
save the file, and restart the portal server.
For example, the following lines would correct the Great Britain (en-gb )
and Ireland (en-ie) locales:
language.25=en_GB
language.26=en_IE
Tip: If the language entries are not numbered as above, adjust the
numerical portions of the new entries as needed to keep all entries
sequential.
Problem: Logging out of the Inline QuickPlace portlet also logs out of
WebSphere Portal
Solution: If users work with the Inline QuickPlace portlet, and they see a
Sign Out button in the portlet, advise them not to click the button -- doing
so logs out of the portal session.
People Finder portlet, people awareness, and Person menu
problems
This section lists problems that may occur with instances of People Finder, or with
person links and the Person menu in any collaborative portlet.
People awareness features are also supported by proper connection to the
Sametime Instant Messaging server configured for use in the portal. For more
information on troubleshooting this server and testing the operation of the stlinks
applet, see Troubleshooting Domino and the Extended Products.
The following table provides an overview of awareness features in collaborative
portlets and how the features are supported.
Portlet
Uses stlinks applet to
support awareness
Uses Person tag to support
awareness
Other awareness
configuration
Lotus Notes View X X Chat and awareness
features can be added by
modifying portlet edit
mode properties
People Finder X
Common Mail X
Common Calendar X
Domino Web Access X Chat and awareness
features can be added by
configuration of Sametime
Instant Messaging server
74 Troubleshooting guide
Portlet
Uses stlinks applet to
support awareness
Uses Person tag to support
awareness
Other awareness
configuration
Inline QuickPlace X Chat and awareness
features can be added by
configuration of QuickPlace
server
Sametime Contact List X
Who Is Here X
Lotus Web Conferencing X
My Lotus QuickPlaces X
Supported browsers for awareness
When a portlet uses STLinks for awareness, the browsers, client platforms, and
versions of Java Virtual Machine supported for awareness in that portlet may be
different from those supported by the portlet itself. The applet supports only the
browsers, client platforms, and versions of JVM or other Java software supported
by the release of Lotus Sametime running on the server configured for
Collaborative Services in the portal. If that release is Lotus Instant Messaging and
Web Conferencing 6.5.1, the browser releases are:
v Internet Explorer Version 6.0 with the following Java and operating system
software:
– Sun JVM 1.4.1 on Microsoft Windows 2000 Professional SP3 or Microsoft
Windows XP Professionalv Internet Explorer Version 5.5 with the following Java and operating system
software:
– Microsoft JVM 1.1 on Microsoft Windows 2000 Professional SP3v Mozilla 1.41 with the following Java and operating system software:
– Sun JVM 1.4.1 on Microsoft Windows 2000 Professional SP3Microsoft
Windows XP Professional SP1
If the Lotus Sametime server is running 7.0, the browser and Java software releases
are:
Browsers
v Internet Explorer 6.0 on Windows XP and Windows 2000 Professional
v Mozilla 1.7.6 on Windows XP Professional and Windows 2000 Professional 3.0
v Mozilla Firefox 1.0.1 on Windows XP Professional and Windows 2000
Professional 3.0
Java JDK/JRE
v Sun JDK and JRE 1.4.2
If the Lotus Sametime server is running 7.5 (supported with
WebSphere Portal 6.0.1 only), the browser and Java software releases are:
Browsers
v Internet Explorer 6.0 on Windows XP Professional
v Mozilla 1.7.12 on Windows XP Professional
Chapter 1. Troubleshooting 75
Java JDK/JRE
v IBM or Sun JDK/JRE 1.4.2 or later - Internet Explorer 6.0 on Windows XP
Professional
Problem: People Finder displays a default Help message instead of quick search
controls
Solution: Remove any fields that People Finder is configured by default to
display that do not also exist in the LDAP directory configured to work
with the portal
If you see the following Help message in People Finder, it means its
default configuration needs to be corrected.
People Finder is an online corporate directory
that lets users search for and view
a colleague’s contact information and
position in the organization’s structure.
Perform the following tasks:
1. Log into the portal as an administrator.
2. Verify that Member Manager has been installed and configured
correctly in your portal.
3. Open People Finder configuration mode (click the wrench icon).
4. For each field you see listed in red under the error message
Attribute_field_name was not found in the directory, examine
every section of the portlet for references to the field, deselect it in the
Attributes and Display Formats table on the Configuration Basics page,
and delete the field in any sections where it appears.
For details on deleting fields, click the Help (question mark) icon in
People Finder.
Tip: If all fields do not disappear after you click Apply Changes Now,
return to configuration mode and examine sections for occurrences
you may have missed. For example, the Person Record page
contains multiple sections under the Select a Section label.
Problem: People Finder shows no results or tells the customer to try searching
later
When a Quick or Advanced search yields more results than are set for the
maximum, customers see no results or an error. The number of results
returned is the smaller of the two values set in the portlet’s configuration
area and the server’s wmm.xml file.
Solution: Allow more search results.
Adjust the setting for the maximumsearchresultsattribute in the portal server’s
wwm.xml file and in the portlet’s configuration parameters.
Problem: The Organization View in the Person Record page does not work
properly
Solution: Ensure correct configuration of the Manager attribute in the
directory.
If the Organization View for found people does not display properly,
ensure that the Manager attribute in the people records of the People
Finder directory is specified properly. The Manager attribute must use the
DistinguishedName (dn), not the CommonName (cn) or other user-visible
76 Troubleshooting guide
value, of a found person’s manager. The DistinguishedName (dn) must be
valid for all LDAP servers configured to work with Domino and Extended
Products Portlets.
Problem: Odd-looking values appear in the Manager and Assistant fields
Solution: Make sure the fields have the correct display format.
The LDAP server probably stores the Manager and Assistant attribute
values in DistinguishedName (dn) format, a type of unique identifier in
LDAP. When, in the Configuration Basics task in People Finder
configuration mode, you select the Manager and Assistant (or Secretary)
attributes to appear as fields in the People Finder portlet, remember to
select Other Person Link as the Display Format for these fields.
Problem: The Person Record or Organization View for a found person cannot be
opened from a person link in a portlet other than People Finder
Solution: Map attributes between LDAP directories.
The Person menu can be used from other portlets to display a found
person’s Person Record or Organizational View. But if the source portlet is
using a different LDAP directory from the one being used by People
Finder, there may be no match if the personal identity attributes of the
LDAP directories apply disparate name formats.
To resolve this discrepancy between identity mismatches, you can use the
ibm-awarenessPerson attribute to add a link from the People Finder LDAP
into another LDAP when person name attributes use different name
formats to establish identity.
For example, if the Lotus Notes View portlet or the My Lotus QuickPlaces
portlet uses a Lotus Domino LDAP Directory, the users in the Lotus
Domino LDAP Directory are probably identified by their Lotus Domino
DistinguishedNames format, cn=Scott Jones,ou=my_company. If, on the
other hand, the People Finder portlet uses an LDAP directory other than
Lotus Domino, that same person is recognized with a DistinguishedName
(dn.) format that might be uid=ssmith,ou=hq,o=my_company. You can create
a link between the two different LDAP directories by mapping attributes.
Problem: Conflicts occur in People Finder due to concurrent updates by multiple
users
The People Finder portlet’s Configuration mode has no locking mechanism
to prevent update conflicts and overrides by multiple users.
Solution: Consider implementing a plan whereby only one administrator
or designer is configuring the People Finder at a given time. Scheduling
and communicating single-user sessions for configuring the People Finder
will alleviate the potential for lost work.
Problem: E-Mail address links may have different behavior in People Finder
than in other portlets such as Lotus Notes View
The default specification for the attribute E-mail address (ibm-primaryEmail)
in the People Finder portlet causes the Send E-Mail action on the Person
menu (available on person links in People Finder) to open a new mail
message in the HTML-based mail application specified in the user’s
browser. This may not match behavior of the same action on the Person
menu in portlets such as Lotus Notes View (when configured as Notes
Mail).
Chapter 1. Troubleshooting 77
Solution: In Configuration mode in the People Finder portlet, specify the
display format People link for the E-mail address attribute.
Problem: The column specified for people awareness in the Lotus Notes View
portlet must contain user names
When the Lotus Notes View portletType parameter is configured as
NOTESMAIL, NOTESDISCUSSION, NOTESTEAMROOM, or
NOTESVIEW, in order to enable people awareness, assist users to identify
and specify a column containing user names in the source database.
Solution: For example, when the portlet is configured as NOTESMAIL,
and a user edits the portlet properties to specify the Column for showing
people awareness, if the view is $Inbox, advise users to select the Who
column from the drop-down list of column names. When the portlet is
configured as NOTESDISCUSSION, if the view is the AuthorView, advise
users to select Column 0.
Problem: Directory Search error behavior may be misleading
Directory Search is a portlet that is used by other portlets to present a
window where users can search for other users by name when performing
tasks such as creating a mail message or adding contacts to a list. When
the maximum search results number for the LDAP directory used by
Member Manager (and therefore by the Directory Search portlet) is set
lower than the number of results yielded by a search, users may see
behavior or errors that are not helpful. Depending on the difference
between the numbers, users may see no error message when they should
see Too many results found, or may see an error message telling them to
perform the search later.
Solution: Increase the setting for the maximumsearchresultsattribute in the
portal server’s wwm.xml file and in the portlet’s configuration parameters.
My Lotus QuickPlaces portlet problems
Problems with the My Lotus QuickPlaces portlet might be the result of faulty
configuration of the QuickPlace server or the portlet.
Problem: My Lotus QuickPlaces portlet cannot connect to the QuickPlace server
Solution: The following error message in the My Lotus QuickPlaces portlet
Connection to QuickPlace Server could not be established
is usually the result of one of the following configuration conditions:
v Your portal user ID is not recognized by the QuickPlace server.
v Single Sign-on (SSO) is not set up properly.
v The QuickPlace server http://yourServer.yourDomain.com:80 is not
running the QPServlet.
v A Reverse Proxy setting is enabled for Pinnacor Portlets; when this
setting is enabled, the My Lotus QuickPlaces portlet becomes unable to
contact the QuickPlace server.
To find the reason for the error, follow this procedure:
1. Make sure your portal ID is current and recognized by the QuickPlace
server.
2. To test SSO between Lotus QuickPlace and WebSphere Portal, log in to
the portal as an administrator and go to the following URL:
http://yourQuickPlaceServer.yourDomain.com/quickplace
78 Troubleshooting guide
If your name does not appear at the top left corner of the screen, SSO is
not working. Resolve SSO issues before proceeding. For more
information, see the SSO technote link at the end of this procedure.
3. To make sure the QPServlet is correctly installed and configured, see
Adding the QPServlet application to the Lotus QuickPlace server.
4. Make sure there is no Reverse Proxy setting enabled for Pinnacor
Portlets, or if there is, obtain a fix for this issue from IBM Support. This
proxy server is set for the entire JVM, and, without the available fix,
prevents the collaborative portlets from being able to contact the
QuickPlace server.
For information on enabling a proxy server for the Pinnacor portlets,
see the following technote:
Technote 1114624 Configuring Pinnacor Portlets to Display Data
For additional information on troubleshooting the server connection, read
the following technotes:
Technote 1158269 Troubleshooting WebSphere Portal, Domino
Extended Products, and Domino SSO Issues
Technote 1159319 Error: ″Connection to QuickPlace Server Could not
Be Established″ in My Lotus Team Workplaces Portlet
Problem: My Lotus QuickPlaces portlet does not appear when first deployed
Solution: If the My Lotus QuickPlaces portlet does not appear when you
first deploy it, try the suggestions listed for the problem described above
with the following message: My Lotus QuickPlaces portlet cannot
connect to the QuickPlace server, especially making sure that the
QPServlet is running.
Problem: Authentication to the QuickPlace server is challenged
If you attempt to open a QuickPlace from the My Lotus QuickPlaces
portlet, and you see a message requiring you to authenticate, then
something is incorrectly configured with SSO between WebSphere Portal
and the QuickPlace server.
Solution: To troubleshoot your configuration, read the following technote:
Technote 1158269 Troubleshooting WebSphere Portal, Domino
Extended Products, and Domino SSO Issues
Problem: Message:PlacesForMember cannot be initialized
This error appears in the My Lotus QuickPlaces portlet,
PlacesForMember could not be initialized via QuickPlaceService
and includes the server host name and user credentials.
Solution: Perform one or more of the following tasks:
v Modify the configuration parameters shown in the error window and
restart the WebSphere Application Server.
v Reinstall the portlet, and log in to the portal again.
v If you see this error again, and the user credentials are valid for logging
in to the QuickPlace server, make sure that at least one Lotus QuickPlace
exists for the user in question.
Chapter 1. Troubleshooting 79
v If user ID is null, an authentication problem exists with the SSO token.
Refer to the topics that address portal authentication with single signon.
Problem: Portlet content is missing or questionable
Solution: Try logging out and logging in again to the portal.
If the information displayed in the portlet is not synchronized with
information on the QuickPlace server, click Refresh to clear the portlet
cache.
Problem: Attribute values invalid according to the specified TLD
The appserver-out.log reports this problem -
TWP=>doView cached Exception: JSPG0126E: Attribute value invalid according
to the specified TLD
Solution: Verify that the latest Collaborative Services files are installed:
Make sure that you have installed (or updated) the latest version of the
Collaborative Services files on the QuickPlace server:
v The Collaborative Services Java archive, cs.jar
v The People Awareness Sametime Links JavaScript file, pa_stlinks.js
v The Person tag language definition file, people.tld
For file locations and other information, see Checklist of tasks: Lotus
QuickPlace server and portlets.
The Domino and Extended Products Portlets installation program looks for
the latest version of these files, which are installed with WebSphere Portal.
Problem: No team places display in portlet
If portlet users do not see a list of their team places (My QuickPlaces) in
the default view of the My Lotus QuickPlaces portlet, they should see the
message You do not belong to any places. When users join one or more
places, the places to which they belong will appear in the My QuickPlaces
list.
Solution: Perform one of the following tasks:
v Make sure that you have added users to the membership lists of existing
team places.
v Create new QuickPlaces and add the new members using correct user
IDs.
Problem: What’s New and My Tasks views do not display the pages of inner
rooms
If you have created a team place that has inner rooms, the My Lotus
QuickPlaces portlet does not show pages from inner rooms in the views
What’s New and My Tasks.
Solution: Redesign team places that are sources for the portlet without
inner rooms.
Problem: Tasks in My Lotus QuickPlaces portlet must be assigned to
individuals, not to groups
If you assign a team place task to a group, members of the group will not
see the task in the My Tasks view of the My Lotus QuickPlaces portlet.
Solution: Make sure that you always assign tasks in My Lotus QuickPlaces
to a specific person.
80 Troubleshooting guide
Problem: Searching for team places before and after a certain date includes the
specified date
The My Lotus QuickPlaces portlet returns results for searches before and
including the specified date, while QuickPlace returns results before and
excluding the specified date. Similarly, the portlet returns results for
searches after and including the specified date, while QuickPlace returns
results after and excluding the specified date.
Solution: Advise users whose searches return unexpected results of these
differences.
Problem: My Lotus QuickPlaces does not work if secure sockets layer (SSL)
protocol is enabled
If you have configured the My Lotus QuickPlaces portlet to run on a
server configured to run secure sockets layer protocol (HTTPS), Lotus
QuickPlace will not appear in the portlet nor will they be available for
search.
Solution: Avoid configuring your QuickPlace server with SSL.
Lotus Web Conferencing portlet problems
Problems with the Lotus Web Conferencing portlet might be the result of faulty
configuration of the Sametime Web Conferencing server or the portlet.
Problem: Cache properties affect portlet performance
The Domino and Extended Products Portlets installation program sets the
LotusMeetings caching properties used by the Web Conferencing portlet.
Solution: Perform one or both of the following tasks:
v Verify that the default settings for cache properties are correct.
v (Optional) Modify the cache settings to improve portlet performance.
To view or modify LotusMeetings cache properties, follow these steps:
1. Access the WP Cache Manager Service, as described in Setting
configuration properties.
2. Verify that the following default values exist and are set:
# LotusMeetingsProperties cache properties
cache.LotusMeetingsProperties.enabled=true
cache.LotusMeetingsProperties.lifetime= 2592000
cache.LotusMeetingsProperties.size=10000
cache.LotusMeetingsProperties.replacement=moderate
cache.LotusMeetingsProperties.admit-threshold=0
3. Add these values if you do not see them in the WP Cache Manager
Service.
4. If necessary, edit the default values to boost the performance of the
portlet.
5. If you add or change any values, restart the portal server.
You can also adjust the setting of the cache.lifetime.in.seconds property in
the LotusWebConferencingUI.properties file. By default, this setting causes
the portlet to check the Sametime Web Conferencing server approximately
every half hour (2000 seconds) to see if any new meetings have been
scheduled. For a very active Sametime Web Conferencing server, one that
hosts a high volume of meetings, you might need to decrease this number
Chapter 1. Troubleshooting 81
for more frequent checks. For a less active Sametime Web Conferencing
server, one that hosts fewer meetings, you might need to increase this
number for infrequent checks.
To adjust the cache.lifetime.in.seconds property, follow these steps:
1. Open the LotusWebConferencingUI.properties file in a text editor.
2. Scroll to the comment line:
# DO NOT TRANSLATE ANY OF THE MESSAGES BELOW THIS POINT
3. After that comment line, find the cache.lifetime.in.seconds property:
# How often to update the cache (2000 seconds = approx 1/2 hour)
# For 1000 meetings on the ST server
# it takes 1000-2000 seconds to retrieve all meeting properties
cache.lifetime.in.seconds = 2000
4. Edit the variable as needed to set the frequency of checks that the Web
Conferencing portlet makes against the Sametime Web Conferencing
server that hosts meetings.
5. Save and close the LotusWebConferencingUI.properties file.
6. Restart the portal server.
Problem: Web Conferencing portlet does not respond immediately when first
deployed in the portal
The first time you deploy the Web Conferencing portlet in the portal, the
portlet needs to load all of the meeting information from the Sametime
Web Conferencing server. This process takes approximately 1 to 2 seconds
for each meeting hosted on the Sametime Web Conferencing server.
Therefore, when the portlet is installed in the portal and added to a page
of the portal, it will not respond immediately.
Solution: The amount of time needed before the portlet responds in a
portal page depends on the number of meetings hosted on the Sametime
Web Conferencing server. For example, if there are 1,000 meetings hosted
on the Sametime Web Conferencing server, expect the Web Conferencing
portlet to take approximately 30 minutes to load. If you have configured
multiple Sametime Web Conferencing servers using clustering to balance
workload, this wait time will be reduced.
Problem: Searching for a meeting yields no results
Solution: If portlet users do not see meetings displayed in the portlet after
a significant period of time, check the following requirements and
conditions:
v The Sametime Web Conferencing server must be up and running.
v The PurgeMeeting agent should be enabled on the Sametime Web
Conferencing server, as described in the configuration prerequisites for
the Lotus Web Conferencing portlet.
v The values specified for the portlet configuration parameters
SametimeSSLX and SametimePortX must be correct.
Problem: Authentication to Sametime Meeting Center is challenged
Users of the Web Conferencing portlet may be prompted for their
credentials (user name and password combinations) when they try to
access the Sametime Meeting Center.
82 Troubleshooting guide
If the SSO token is not being shared properly between the portal server
and the Sametime Web Conferencing server, portlet users might be
re-challenged for their credentials when using the Lotus Web Conferencing
portlet in the following contexts:
v Attending a meeting
v Testing a meeting
v Replaying a meeting
v Accessing the Sametime Meeting Center
Solution: Verify that SSO is working properly between the portal server
and the Sametime Web Conferencing server. Perform the following steps:
1. Launch your browser and log in to the portal with your user name and
password.
Example: http://yourPortalServer.yourDomain.com/wps/portal
2. In the same browser session, type the URL for your Sametime Web
Conferencing server.
Example: http://yourWebConferencingServer.yourDomain.com/stcenter.nsf
3. Click Attend a Meeting.
If you see your name at the top right corner of the screen, SSO is
working properly.
If your name does not appear at the top left corner of the screen, SSO is
not working. Resolve SSO issues before proceeding. Read the following
technote:
Technote 1158269 Troubleshooting WebSphere Portal, Domino
Extended Products, and Domino SSO Issues
Problem: Poor performance hinders portlet use
Solution: Check the cache properties of the portlet and the Sametime
Meeting agents that control performance factors. Perform the following
tasks:
v Ensure that the PurgeMeeting agent is set appropriately, as described in
the configuration prerequisites for the Lotus Web Conferencing portlet.
v Check the settings for the LotusMeetings caching properties used by the
Web Conferencing portlet, specifically the cache size and cache objects
lifetime, as described in Cache properties affect portlet performance.
Problem: Lotus Web Conferencing portlet does not display properly
Solution: Try checking the LotusWeb ConferencingUI.properties file to see
the default UI settings and the location of JSPs that render the views of the
portlet. You will also need to know the location of the portlet JSPs if you
intend to customize the portlet.
To verify and edit the default settings of the
LotusWebConferencingUI.properties file, follow these steps:
1. Open the LotusWebConferencingUI.properties file in a text editor.
2. Scroll to the comment line:
# DO NOT TRANSLATE ANY OF THE MESSAGES BELOW THIS POINT
3. After that comment line, find the following properties to verify and
edit, if necessary:
You can change the path to a JSP that renders a main view of the
portlet:
Chapter 1. Troubleshooting 83
#Main JSPs
ResultURI = /jsp/html/ViewResult.jsp
DetailURI = /jsp/html/ViewDetail.jsp
NewMeetingURI = /jsp/html/ViewNewMeeting.jsp
EditMeetingURI = /jsp/html/ViewNewMeeting.jsp
EditURI = /jsp/html/Edit.jsp
ConfigureURI = /jsp/html/Configure.jsp
ErrorURI = /jsp/html/Error.jsp
MessageURI = /jsp/html/ViewMessage.jsp
You can change the path of a JSP that renders a particular element of a
view:#JSP location
jsp.detail = /jsp/html/Detail.jsp
jsp.menu = /jsp/html/Menu.jsp
jsp.list = /jsp/html/List.jsp
jsp.search = /jsp/html/Search.jsp
jsp.menu.list= /jsp/html/ListMenu.jsp
jsp.menu.top.list = /jsp/html/ListMenuTop.jsp
jsp.newMeeting = /jsp/html/NewMeeting.jsp
jsp.menu.edit = /jsp/html/EditMenu.jsp
jsp.menu.newMeeting = /jsp/html/NewMeetingMenu.jsp
jsp.menu.detail = /jsp/html/DetailMenu.jsp
jsp.menu.search = /jsp/html/SearchMenu.jsp
jsp.message = /jsp/html/Message.jsp
jsp.menu.message = /jsp/html/MessageMenu.jsp
You can change the path of a JSP that renders the images used by the
portlet:# Image locations
image.go = /images/go
image.back = /images/close
image.back.small = /images/lt-an-canceliconsmall
image.next = /images/next
image.previous = /images/previous
image.save = /images/register
image.error = /images/error
image.divider = /images/divider
image.dot = /images/dot
image.attachment = /images/attachment
image.new.meeting = /images/add
image.advanced.meeting = /images/meetingcenter
image.test.meeting = /images/lt-an-testmtgicon
image.edit.meeting = /images/edit
image.delete.meeting = /images/delete
image.information = /images/inlineHelp
image.reset = /images/reset
You can change the properties that specify the Lotus Sametime server
port ID and the enablement of Secure Sockets Layer (SSL):# Default port and SSL values
default.st.port = 80
default.st.useSSL = no
4. Edit the properties as needed.
5. Save and close the LotusWebConferencingUI.properties file.
6. Restart the portal server for the changes to take effect.
Problem: Lotus Web Conferencing portlet yields password errors when users try
to create or search for meetings
Users who attempt to create a new meeting or search for an existing
meeting may see one of the following errors in the portlet:
v Passwords cannot contain special characters. Enter a different
password.
84 Troubleshooting guide
v Unable to access Sametime due to incorrect logon
Solution: Read and try the suggested solutions in the following technote:
Technote 1170825 Password Errors When Using Web Conferencing
Portlet
Problem: Meeting attachments sometimes do not appear in the Web
Conferencing portlet
Solution: If your meeting contains attachments and these attachments do
not appear when you open the meeting using the Web Conferencing
portlet, verify that the Lotus Sametime server has any necessary interim
fixes that correct this problem.
Who Is Here portlet problems
Problems with the Who Is Here portlet might be the result of faulty configuration
of the Sametime Instant Messaging server or the portlet.
Sametime Contact List portlet problems
Problems with the Sametime Contact List portlet might be the result of faulty
configuration of the Sametime Instant Messaging server, the portlet, or the user’s
browser software.
Problem: Sametime Contact List portlet is not completely accessible with JAWS
screen reader
Users of the JAWS screen reader software may have difficulty selecting
radio buttons in the Sametime Contact List portlet.
Solution: Use screen reader software other than JAWS.
Lotus Notes View portlet problems
Problems with the Lotus Notes View portlet might be the result of faulty
configuration of the Lotus Domino server that contains source database(s) for the
portlet, the portlet, or the user’s browser software. Some problems occur only in
instances of the portlet whose portletType parameter is configured with specific
values, such as NOTESVIEW.
Problem: Notes portlets of certain types do not resolve the Lotus Domino
messaging/application server and database for authenticated portal users when
the corporate LDAP service is not Lotus Domino LDAP
When Lotus Domino LDAP is not configured as the Domino Directory for
the Collaborative Services service for WebSphere Portal, the Lotus Notes
View portlet, when configured with a portlet type of either MYINBOX (My
Notes Mail - Inbox), MYCALENDAR (My Notes Mail - Calendar), or
MYTODO (My Notes Mail - To Do), may fail to resolve the mail file and
mail server information. Consequently, the portlet displays an ERROR
MAILINFO link. Clicking the error link results in another error message
indicating that portlet content cannot be displayed because the Lotus
Domino server does not recognize the user name and password used to
log in to the portal.
Solution: See About automatic detection of mail files.
Problem: Deleting a document in one instance of the Lotus Notes View portlet
does not refresh other instances of the portlet that are above it on the portal
Chapter 1. Troubleshooting 85
page
This problem can occur when multiple instances of the Lotus Notes View
portlet, deployed on the same portal page, display the same document in
the same source Notes database. If a user deletes a document from a
portlet that is below another portlet displaying the same document, any
portlets above do not refresh to show the deletion.
Solution: Advise users to delete the document from the first portlet
deployed on the page, and the portlets below it will refresh.
Note: In some situations users, or you as portal administrator if you
populate portal pages, should always place certain portlet types
above others on a portal page. For example, if the first instance of
Lotus Notes View is configured with a portlet type of
MYCALENDAR (My Notes Mail - Calendar) and the second is
configured with a portlet type of MYTODO (My Notes Mail - To
Do), showing the same source database, deleting documents from
the My Notes Mail - To Do portlet will not refresh the My Notes
Mail - Calendar portlet because it is above the My Notes Mail - To
Do portlet. Users also cannot delete documents directly from the My
Notes Mail - Calendar portlet, so this arrangement is not useful. The
My Notes Mail - Calendar portlet should always be placed below a
My Notes Mail - To Do portlet displaying the same source database.
Problem: In the Lotus Notes View portlet, specifying view or server names by
typing may not work
If users edit the Lotus Notes View portlet and attempt to add a view by
typing a visible view title such as ″All Documents,″ the view may not be
saved in the portlet. In addition, typing a view or server name that
contains a double quote (″) character does not work.
Solution: Advise users to select view and server names from the
drop-down lists provided instead of typing names. Also, if users are
familiar with Notes database design and know view alias names (for
example, ($All) instead of All Documents), typing an alias name works to
specify a view.
Problem: In the Lotus Notes View portlet, no error message appears when users
attempt to add views to which they have no access in the source database
Solution: If a user cannot add views to this portlet from a specific
database, examine the ACL of the source database and correct it if it is set
to No Access for the user.
Problem: In the Lotus Notes View portlet, options that open new windows in
the Lotus Notes client software may function improperly if Notes is not already
launched
If users edit the properties of the portlet and specify Lotus Notes, if available
for the View documents in option, but do not launch the Note client
software ahead of time, login errors may occur, or view focus may be
incorrect, when users take actions, such as creating a mail message, that
require Lotus Notes to open a new window.
Solution: Advise users to launch the Lotus Notes client software, and enter
their Notes password, before using the Lotus Notes View portlet when the
Lotus Notes, if available option is specified.
86 Troubleshooting guide
Problem: Difficulty editing repeating tasks or calendar documents in the Lotus
Notes View portlet
If the Lotus Notes View portlet displays a To Do view or Meetings view,
editing repeating tasks or calendar documents (for example, meetings)
requires specific steps. For example, when a user selects a repeating item
and then selects Edit from the drop-down list under the Actions (down
arrow) icon, a dialog box may display dates incorrectly so that a single
instance of the task cannot be selected. In addition, editing the parent
document of a set of repeating items causes problems in the way Notes
manages the documents.
Solution: To edit any repeating item, users must select one of the instances
of the item (not the parent item) and select Open, instead of Edit, from the
Actions drop-down list. Selecting Open displays a dialog box where users
can specify which repeating item they want to edit. In some cases the
dialog box does not appear; if this happens, users can edit only the first
repeating item.
Problem: Edits to title of Lotus Notes View portlet may persist even when user
clicks Cancel
Solution: If the Lotus Notes View portlet is configured with a portlet type
of MYCALENDAR (My Notes Mail - Calendar) or MYINBOX (My Notes
Mail - Inbox), and users edit the portlet title, advise them to make sure the
title is correct before saving changes to the portlet properties.
Problem: In some portal configurations, drop-down lists for selecting server and
database for the Lotus Notes View portlet display incorrectly
If the portal configuration runs SSL, does not support DIIOP, or restricts
access to Java, JavaScript, or COM run by portal users, editing properties
for the Lotus Notes View portlet may not work correctly. Users may notice
drop-down lists for selecting a source Notes server and database painting
incorrectly with check mark icons out of place, obscuring buttons at the
bottom of the screen.
Solution: Users can still make entries in the drop-down lists, and click
buttons such as Done at the top of the screen.
Problem: In the Lotus Notes View portlet, deleting calendar documents directly
does not allow proper workflow
When the Lotus Notes View portlet is configured to display a calendar or
meetings view, selecting Delete from the Actions drop-down list for a
document deletes the document, but does not properly manage the
deletion. For example, deleting a meeting does not inform invitees that the
meeting has been canceled.
Solution: Advise users to select Open instead of Delete from the Actions
drop-down list, and then click the Delete action in the separate browser
window that appears.
Problem: In the Lotus Notes View portlet, the icon for creating new documents
does not work if specified form has a space character in its name
This problem occurs when users set up a view in a Lotus Notes View
portlet, specify an icon for creating documents, specify a form that has a
space in its name, and also set the View documents in option to Lotus
Notes, if available.
Chapter 1. Troubleshooting 87
Solution: Advise users to specify only forms that have no space characters
in their names in the source Notes database. If necessary, ask the database
designer to adjust form names.
Problem: In Lotus Notes View portlet, selecting Switch ID causes unexpected
behavior
There are several problems.
v The portlet re-displays in the maximized state after switching ID, and
may cause users to assume other portlets have disappeared from the
current page.
v When the portletType is set to MYINBOX (My Notes Mail - Inbox),
switching ID between users who have different releases of source mail
(for example, Lotus Domino 6.03 and 6.5) can cause the view to appear
blank. Also, when columns are specified to display people awareness
and launch documents, the settings may change to inappropriate
columns.
Solution: Take one of these actions:
v To correct the problem with maximizing, advise users to select Restore
from the drop-down menu on the title bar of the portlet after switching
to a different ID in this portlet.
v To correct the problem with the blank view of mail, remove the portlet
from the portal page and re-add it.
v To correct the problem with column settings, avoid using Switch ID;
advise each user to log into the portal.
Domino Web Access portlet problems
Problems with the Domino Web Access portlet might be the result of faulty
configuration of the Lotus Domino server, the portlet, or the user’s browser
software.
Problem: Logging out of the Domino Web Access (iNotes) portlet also logs out
of WebSphere Portal
Solution: If users of the functional areas All or Welcome in this portlet see
a Logout button, advise them not to click the button -- doing so logs out of
the WebSphere Portal session.
Problem: Some parameters for Domino Web Access portlet may disappear when
saving portlet configuration
If a portal administrator edits and saves the Domino Web Access (iNotes)
portlet configuration using Portlet Management, three parameters that are
blank by default -- PortNumber, UseReverseProxyString, and
reverseProxyPortNumber -- disappear from the list of parameters for the
portlet.
Solution: To specify values for any of these parameters, type the
parameter’s name in the blank left field at the bottom of the list, type the
desired value in the right field, and click the Add button.
Problem: Cannot create calendar entries in Domino Web Access portlet when
source database design is UseiNotesTemplate
If users’ source mail databases have the UseiNotesTemplate design, and the
Lotus Domino server is earlier or later than Domino 6.01, users of the
Domino Web Access portlet cannot create calendar entries directly in the
portlet. Solution:
88 Troubleshooting guide
Advise users to click Launch Application and create calendar entries in the
new window that opens.
Problem: Lotus Notes View portlet set with new parameter can cause loss of
access to iNotes mail design
The UseiNotesTemplate parameter, when enabled in the Lotus Notes View
portlet, allows iNotes users to access their iNotes mail through the Lotus
Notes View portlet and take advantage of people awareness in the portlet.
However, if a user adds an instance of the Lotus Notes View portlet that is
not enhanced with this parameter, and the Domino Web Access (iNotes)
portlet to the same portal page, and then uses the Lotus Notes View
portlet to access mail that uses the iNotes design, both the Lotus Notes
View portlet and the Domino Web Access portlet fail to load the iNotes
mail design, and provide only the Notes mail design.
Solution: If your collaborative portal is new and you have not yet set up
user access for creation of portlets, the simple solution is to prevent users
of the Domino Web Access (iNotes) portlet from adding instances of the
Lotus Notes View portlet to their pages, so that these two portlets will
never coexist.
If you have an existing portal where users already have access to add
portlets, and have added instances of the Lotus Notes View portlet that are
not configured with the UseiNotesTemplate parameter, any users whose
source mail has the iNotes design and who attempt to access their mail
using the Lotus Notes View portlet will encounter the error. Take the
following steps:
v Advise users not to mix instances of these two portlets on pages. Users
should rely on the appropriate portlet for their source mail database.
v If all your users have iNotes mail designs, remove instances of the Lotus
Notes View portlet that do not have the UseiNotesTemplate parameter
from availability for future deployment.
v On any page where a user has encountered the error, to correct the error
on that page, deploy a new instance of the Domino Web Access portlet,
and create a new mail memo in the portlet.
Domino Document Manager portlet problems
Problems with the Domino Document Manager portlet might be the result of faulty
configuration of the Lotus Domino server running Lotus Domino Document
Manager software, the portlet, or the user’s browser software.
Problem: Cursor focus can be incorrect when entering user name for Domino
Document Manager portlet
In portlets that use the iFrame feature, when users type in a text input
field using Microsoft Internet Explorer, cursor focus can unexpectedly shift
to areas of the portlet outside the field. This happens when the iFrame
points to a Web site that automatically moves focus to a text input field,
and users move in or out of edit mode, or maximize or minimize the
portlet.
Solution: Advise users to click inside any input field before typing.
Chapter 1. Troubleshooting 89
Troubleshooting Document Manager
This section contains information that can assist you in preventing, identifying, and
correcting problems related to Document Manager.
v “Error message when displaying Microsoft PowerPoint or Excel documents” on
page 91
v “Using the accessibility toolbar in Rich Text Editor and Netscape” on page 91
v “When deleting a large library, the system times out or seems to stop” on page
91
v “Search fails with ″failed to load″ error” on page 91
v “Importing large documents in Portal Document may fail with a
RollBackException error” on page 92
v “Document Manager plugin is not supported for Apple Mac systems when
using the Firefox 1.5 browser” on page 92
v “Using Apple Safari browser, unable to exit Document Manager” on page 92
v “Document Manager table list is incomplete during initial access” on page 92
v “Import error 12002 on IBM DB2 Universal Database for z/OS” on page 93
v “Unable to link to Document Manager from Personalization preview or the
Personalized List portlet” on page 93
v “Missing buttons and file tree view” on page 93
v “Installation of Document Manager plug-in prevented when using an IPv6
(Internet Protocol version 6) Web address” on page 93
v “Previewing 100MB file might result in an error” on page 94
v “Using the timeout feature in DCS for Stellent conversions” on page 94
v “Unable to upload large file (10MB to 500MB) to Document Manager” on page
94
v “Javascript errors occur when Document Manager plug-in is not installed” on
page 96
v “Unable to remove documents from Private Drafts or Locked Documents views”
on page 96
v “An error occurs when importing large files using the Cloudscape database” on
page 97
v “Error condition 12030 occurs when importing large files using Domino
WebServer 6.5.5” on page 97
v “Setting the JVM max heap size to enable file importing” on page 97
v “Preview of large documents fails in Document Manager” on page 98
v “Unable to open an Excel document using Internet Explorer 6.0 SP1” on page 98
v “Loss of unsupported features upon conversion” on page 98
– “Document Viewer ” on page 98
– “Rich Text Editor ” on page 99v “Problems viewing documents as HTML” on page 99
v “Problems with searching specific language documents” on page 104
v “Problems with Document Conversion Services” on page 105
v “Problems with SearchML” on page 106
v “Known limitations of Rich Text Editor” on page 106
v “Known limitations of HTML preview” on page 125
v “Stellent 8.0.1 compatible platforms” on page 126
90 Troubleshooting guide
v “Known limitations for Document Manager” on page 127
v “Known limitations for Document Libraries” on page 134
v Known limitations for desktop components
v “Troubleshooting Document Manager” on page 90
v
“Search fails and DB2 encounters errors with message 00C90096”
on page 137
Error message when displaying Microsoft PowerPoint or Excel
documents
When viewing Microsoft PowerPoint or Excel documents from Document Manager,
an error message is displayed. When you click on the document name of a
PowerPoint or Excel document, a message box appears that says: The file
MSVCP60.dll can not be found. If you click the OK button in this message
window, the document is displayed.
Using the accessibility toolbar in Rich Text Editor and Netscape
Pressing the Ctrl+Shift+m key sequence should bring up the accessibility toolbar in
the Rich Text Editor. However, if you are using the Netscape browser, you must
follow these steps to bring up the accessibility toolbar:
1. Using the Netscape browser, open the Rich Text Editor from Document
Manager by creating a new RTE document or editing an existing RTE
document.
2. Click inside the editing window in the Rich Text Editor.
3. Press the Ctrl+Shift+m key sequence.
When deleting a large library, the system times out or seems to
stop
Problem: If the portal server is configured with a remote database, such as DB2,
you may experience difficulty when trying to delete a large document library
(5,000 or more files). The symptoms might include:
v When the deletion process has been running some time, it seems to have
stopped, or timed out, with the library name still in the list of libraries.
v If you refresh the library list, you see the response Error 409: EJPEJ0096E: Your
previous request is still being processed. Wait a few moments and try
again.
v If you open a new browser and try to delete the library again, you see the
response An error occurred while trying to delete the document library. If
you look in the server log, you see the exception message path does not exist.
Solution: Wait longer for the delete process to complete. The delete is being
processed in the background and will eventually finish.
Search fails with ″failed to load″ error
Problem: During heavy usage of Document Manager in a data-sharing DB2
database using RRS, the maximum number of concurrent identify level agents can
be exceeded. The resulting error message is similar to the following example:
Chapter 1. Troubleshooting 91
ExtendedMessage: BBOO0220E: SCHD0104E: The Scheduler poll daemon WPSTaskScheduler (wps/Scheduler)
failed to load tasks from the database due to an exception: java.sql.SQLException: [IBM/DB2]
[T2zos/2.7.72]T2zosReusableConnection.flowConnect:DB2AttachInterface:initRRSAFAttach:1064:RRS
Identify failed,Return Code=8, Reason Code=X00F30055,Subsystem ID:DS02,Plan Name:,
Pklist:NULLID.*DSRA0010E: SQL State = null, Error Code = -99,999DSRA0010E: SQL State = null,
Error Code = -99,999
Solution: Increase the values in the DB2 DSNTIPE panel as follows:
IDFORE=100
IDBACK=1800
Importing large documents in Portal Document may fail with a
RollBackException error
Problem: Importing large documents in Document Manager may fail with the
following errors in the logs:
javax.transaction.RollbackException
at com.ibm.ws.Transaction.JTA.TransactionImpl.stage3CommitProcessing(TransactionImpl.java(Compiled Code))
at com.ibm.ws.Transaction.JTA.TransactionImpl.processCommit(TransactionImpl.java(Compiled Code))
at com.ibm.ws.Transaction.JTA.TransactionImpl.commit(TransactionImpl.java(Compiled Code))
at com.ibm.ws.Transaction.JTA.TranManagerImpl.commit(TranManagerImpl.java(Compiled Code))
at com.ibm.ws.Transaction.JTA.TranManagerSet.commit(TranManagerSet.java(Compiled Code))
at com.ibm.ws.Transaction.JTA.UserTransactionImpl.commit(UserTransactionImpl.java(Compiled Code))
at com.ibm.icm.ci.JCRUserTransaction.commit(JCRUserTransaction.java(Compiled Code))
at com.ibm.icm.ci.JTATransaction.commit(JTATransaction.java:176)
at com.ibm.icm.jcr.NodeImpl.save(NodeImpl.java:2479)
Solution: Rollback exceptions may be caused by a slow network. Less distance
between servers, and more bandwidth between the database and the server, can
reduce errors, particularly when dealing with large files in Document Manager.
Document Manager plugin is not supported for Apple Mac
systems when using the Firefox 1.5 browser
See the topic Supported hardware and software for WebSphere Portal Version 6.0,
and the section Supported Web browsers, for a list of fully supported browsers.
Using Apple Safari browser, unable to exit Document Manager
Problem: If you navigate to Document Manager using the Safari browser, then
click Cancel when prompted to install the plug-in, you will not be able to use the
contextual menus (Launch button) to exit Document Manager. The menu is
displayed up but no items can be selected.
Solution: A workaround is to click Go instead of Cancel when prompted to install
the plug-in. The plug-in installation page opens. Now you can close the plug-in
installation and exit Document Manager. Apple Safari browser support for
WebSphere Portal is limited. Document Manager does not work at all with Safari.
See the topic Supported hardware and software for WebSphere Portal Version 6.0,
and the section Supported Web browsers, for a list of fully supported browsers.
Document Manager table list is incomplete during initial access
Problem: When Document Manager is initially installed, and you view the
document library table list of contents, the table might display only icons and no
text, or only the document titles with no icons.
92 Troubleshooting guide
Solution: Restart the Document Manager Web application or the WebSphere Portal
server.
Import error 12002 on IBM DB2 Universal Database for z/OS
Problem: A timeout error 12002 occurs when uploading files larger then 100 MB
on DB2 for z/OS.
Solution: The timeout problem occurs because of the slow response time from
DB2. The workaround is to improve the DB2 throughput. For more information,
refer to the DB2 performance tuning guide, which is part of the DB2 installation.
Unable to link to Document Manager from Personalization
preview or the Personalized List portlet
Problem: Using Personalization preview and the Personalized List portlet, you
might be unable to generate links to Document Manager documents under the
following conditions:
v No Document Manager portlet has ever been visited by any user on that portal.
In this situation, one of the following messages is output to the error logs: The
specified document library has not been registered or PDM Category is not
registered.
v The document library to which the document belongs is not configured on any
Document Manager portlet, or that Document Manager portlet has never been
visited by any user on the portal.
Solution: Register the document library to a portlet and visit the portlet using an
account with the appropriate permissions.
Missing buttons and file tree view
Problem: If you use the XML configuration interface to transfer a portal
configuration that includes Document Manager, buttons and the file tree view
might be missing from the user interface panels in Document Manager.
Solution: When the Document Manager Web module is redeployed, its groups
must be mapped to the All Authenticated group in WebSphere. To map the groups,
follow these steps:
1. Log in to the WebSphere Application Server administrative console.
2. Select the Document Manager application, as follows:
a. Expand Applications.
b. Select Enterprise Applications.
c. Locate the application that starts with Document Manager.3. Click Map Security Roles to Users/Groups.
4. Assign the Authenticated role to the All Authenticated group.
5. Save your changes.
6. Restart the portal.
Installation of Document Manager plug-in prevented when using
an IPv6 (Internet Protocol version 6) Web address
Problem: Many Document Manager functions depend on the installation of the
Document Manager plug-in on your local system. If you use a Netscape, Firefox or
Chapter 1. Troubleshooting 93
Internet Explorer 7 browser, and try to access a portal server using an IPv6 URL
(Web address), the URL is not accepted correctly, and this prevents installation of
the plug-in. An IPv6 URL looks like this: http://[2002:92a:8f7a:20:9:42:81:231]:10038/wps/portal.
A Web site must be accepted as valid or trusted by the browser before installation
of the plug-in can be completed. Firefox, Netscape and Internet Explorer 7
browsers do not accept IPv6 Web sites addresses as valid or trusted. This is due to
a bug in these browsers.
Solution: To install the Document Manager plug-in, use an IPv4 URL instead
(example: http://www.ibm.com:10038/wps/portal.
Or, configure the following settings in Internet Explorer 7:
1. Click Tools > Internet Options....
2. Click the Security tab.
3. Select Trusted sites.
4. Click Sites.
5. Type http://[2002:92a:8f7a:20:9:42:82:232] in the Add this website to the
zone: text box and click Add.
6. Click Close.
7. Click OK.
Previewing 100MB file might result in an error
Problem: If you attempt to preview a 100MB file in Document Manager, you might
see this error message on the preview page:
The document contents could not be previewed. You must download
the document to view the contents.
Solution: Download the document to your local system to preview.
Using the timeout feature in DCS for Stellent conversions
Problem: Viewing large-ized files of 100 MB or more in the HTML preview may
cause Document Manager to hang.
Solution: The timeout feature can be used to terminate the conversion process so
that Document Manager doesn’t hang. To enable the timeout feature, go
toportal_server_root/shared/app/converters.xml, and in the Converters.xml file,
change the TIMEOUT parameter value to ’x’ where x is the time in seconds after
which the conversion process should terminate.
Unable to upload large file (10MB to 500MB) to Document
Manager
Problem: Document Manager has the ability to store documents up to 500MB in
size. However, there are several factors that limit actually uploading documents
this large.
Solution: Adjust the following settings to maximize the ability of Document
Manager to upload large documents:
PostSizeLimit setting
94 Troubleshooting guide
You can change the PostSizeLimit setting in the plugin-cfg.xml file, located in the
\AppServer\config\cells directory, to allow documents larger than 10MB to be
uploaded into Document Manager. If an HTTP server is being used in front of
your portal server you will have to modify the PostSizeLimit to upload documents
larger than 10MB. The PostSizeLimit value determines the maximum size
document that can be uploaded. The default value for PostSizeLimit is 10000000
(10MB). Increase this value to 500000000 (500MB). This is the maximum file size
supported by Document Manager.
Transaction timeout value
The transaction timeout value is the maximum duration (in seconds) for
transactions to run on the server before an automatic rollback is issued. This could
also be an issue when uploading larger files under load. The default value for this
setting is 2 minutes. Increasing the value of this timeout will allow larger files to
be uploaded. Experiment with different values for this setting to get it right for
your configuration. If the transaction timeout value is a problem you will see a
message similar to the following in the SystemOut.log:
WTRN0066W: Transaction (2633625)
0001bba9:00000001e0282f991485e7d9a33267078cf208da52b2bc4bd3055b3adf[]
has timed out after 120 seconds.
You can modify the value for the transaction timeout value by going to the
adminisrtative console and following these instructions:
1. Select Servers → Application Servers → WebSphere_Portal → Container Services
→ Transaction Service.
2. Set the Total Transaction lifetime timeout.
Maximize JVM heap size
Database drivers can read large portions of binaries into memory depending on
setup and capabilities. Increasing the maximum JVM heap size on the portal server
is recommended to work around this problem. See the Portal tuning guide for
recommended upper values. The tuning guide is available from this Web page
under the category Performance Guides: http://www.ibm.com/websphere/portal/library.
Other factors that can affect the upload of large documents include:
Browser timeouts
Uploading documents to Document Manager is done via the browser. Depending
on the speed of the network connection to the server, and the size of the
document, the upload could take a long time. During this time your browser
session might time out, resulting in a file upload failure.
Portal server load
The more load the target portal server is under, the more likely it is that timeouts
will occur when trying to upload large files. Uploading large documents during
off-peak usage hours can help limit this impact.
Chapter 1. Troubleshooting 95
Javascript errors occur when Document Manager plug-in is not
installed
Problem: If the Document Manager plug-in is not installed, Document Manager
pages are displayed with Javascript errors. Document libraries can be configured to
enable or disable installation of the Document Manager plug-in. If you do not
want to be prompted to install theDocument Manager plug-in in your browser,
you can configure the document library to disable the plug-in installation.
However, if you choose not to install the plug-in when prompted, there will be
Javascript errors on the Document Manager page.
Solution: To disable the installation of the Document Manager plug-in for a
document library, follow these steps:
1. Log in to Document Manager and navigate to the document library where you
want to disable the plug-in installation.
2. Click on the right-hand drop-down menu and click Configure.
3. Click to deselect Enable browser plug-in.
4. Click Save to save the document library configuration.
Unable to remove documents from Private Drafts or Locked
Documents views
Problem: When a portal user is deleted, then a user with the same name is added
to the portal, draft or locked documents created by the deleted user appear in the
new user’s Private Drafts or Locked Documents view. Because the permissions
assigned to the newer user do not apply to the documents created under the
deleted user account, the newer user is unable to remove these documents. Details
of the document behavior are:
v If User1 is deleted, then:
– drafts submitted by User1 cannot be accepted.
– drafts submitted by User1 can be rejected.
– private drafts authored by User1 are no longer available.
– published documents that have a private draft authored by User1 cannot be
deleted.v If User1 is re-added, then:
– submitted drafts that were rejected now appear in User1’s Private Drafts
view.
– private drafts that were authored by the previous User1 cannot be deleted or
modified.
– published documents that have private drafts authored by the previous User1
cannot be deleted.
– even if locking is disabled in the document library, any documents locked by
the previous User1 remain locked.
Note: This locking scenario always occurs when locking is enabled for a
document library, and a user locks a document, and then locking is
disabled. The document remains locked.
96 Troubleshooting guide
An error occurs when importing large files using the Cloudscape
database
Problem: When importing a file greater than 100 MB in size, using Document
Manager and the Cloudscape database, an error occurs and the import process
fails.
This is a known limitation of the Cloudscape database.
Error condition 12030 occurs when importing large files using
Domino WebServer 6.5.5
Problem: When importing a file greater than 10 MB in size, using Document
Manager and Domino WebServer 6.5.5, the error condition 12030 occurs and the
import process fails.
Solution: By default, the Domino Webserver limits the post request size to 10 MB.
When importing larger files, the HTTP configuration parameter needs to be
modified as follows:
v Maximum Post Data Size must be modified to the size of the file to be
downloaded
v Request Content Size should be set to zero (0) to allow unlimited content size
Setting the JVM max heap size to enable file importing
Problem: When importing files into a document library while running indexing at
the same time, or when importing large documents, an out of memory error might
appear, or a portal crash might occur.
Solution: During text indexing of imported documents, the binary conversion
routine might run out of memory writing out the converted string buffer. This
problem is encountered with very large text files, or large files stored in a zip file
format such as Word documents or PowerPoint presentations. The file size limit is
determined by the size of the JVM heapsize. For example, the typical JVM heapsize
is 512MB. A 75MB zip file may expand into over 300MB in size and cause the out
of memory error, depending on how much of the heap is being used by other parts
of the application. Avoid importing extremely large files into Portal Document
Manager.
If you must import large files, the out of memory error can be avoided by tuning
the portal for performance, which involves setting the JVM max heap size limits,
as described below:
v From the WebSphere Application Server Administration Console, select Servers
→ Application Servers → yourPortalServerName → Java and Process Management
→ Process Definition → Servant → Java Virtual Machine → Maximum Heap Size
to set the JVM heap size.
v Make sure that the system has enough physical memory for all of the processes
to fit into physical memory, plus enough for the operating system. When more
memory is allocated than the physical memory in the system, paging will occur,
and this can result in very poor performance.
v After doing any tuning of heap sizes, monitor the system to make sure that
paging is not occurring. As mentioned above, paging can cause poor
performance.
Chapter 1. Troubleshooting 97
v WebSphere Portal runs with an 31 bit JVM. Therefore, the address space limit is
2 GB. The JVM heap size should be set to 768 MB maximum because WebSphere
Portal also fits into the same address space. You can find more information at
Java virtual machine storage tuning tips for z/OS. Also refer to Tuning
performance.
Preview of large documents fails in Document Manager
Problem: When previewing a large document, such as a 10MB or larger document,
Document Manager might display out of memory errors, or might stop working.
Solution: Increase the JVM heap size as specified in the troubleshooting item
“Setting the JVM max heap size to enable file importing” on page 97. In addition,
you should consult the WebSphere Portal Performance Tuning Guide to ensure that
the capacity of the entire portal environment is greater than the intended use.
Tuning guides for various versions of WebSphere Portal are available on the
Product Documentation Web site: http://www.ibm.com/websphere/portal/library.
Unable to open an Excel document using Internet Explorer 6.0
SP1
Problem: When you download an Excel document stored in Document Manager
and select Open, the second time the document is downloaded, the open
command might fail. This occurs only in Internet Explorer 6.0 SP1, the version that
is included in Windows 2000 and Windows XP prior to SP2. A cache problem in
Internet Explorer 6.0 SP1 prevents the call to Document Manager to re-send the
Excel document.
Solution: A workaround can resolve the problem temporarily. In Internet Explorer,
click on Tools → Internet Options → Delete Files and select Delete all offline
content. Restart the browser.
Loss of unsupported features upon conversion
Using Document Conversion Services, Document Manager can view and edit many
document formats via the document conversion framework. As with any document
conversion, however, some loss of formatting and features is expected.
The following list details some reasons why documents viewed using Document
Conversion Services do not retain all of the features of the program they were
created in:
v The source document uses features not available in the default Rich Text Editor.
v Conversion from the source document to the target document requires a lossy
conversion. For example: vector graphics might be converted to bitmaps on the
server.
v The source application has more formatting and styling options than the default
Rich Text Editor.
Document Viewer
The viewer makes a read-only HTML rendering of the source document. The
business information of the source document should be preserved, though the
styles and formatting might diverge from the original. In particular, graphical file
98 Troubleshooting guide
formats, such as Freelance Graphics or PowerPoint, render as JPEGs, one per slide.
This conversion relies on the graphical capabilities and settings on the server,
including:
v available fonts
v resolution
v color depth
For best results, users should ensure that the server has the same fonts available as
used in the source documents, and that the color depth of the server matches that
of the majority of the clients.
Rich Text Editor
The Rich Text Editor uses HTML as its document format. The following features
are lost in conversion:
v Page-level constructs, such as headers, footers, page numbers, and hard page
breaks are not part of HTML. So page breaks will be lost and repeating
page-level text, such as headers and footers, will be inline on each page.
v Graphics within text blocks can change position, since the ability to position
graphics within text blocks is more constrained in HTML than in full-functioned
word processors.
v Text control depends on which client browser you use. These controls differ in
the details of text layout, especially with regards to complex tables.
v Client differences, especially across a heterogeneous client platform base, can
affect fidelity, especially with regards to available fonts.
Problems viewing documents as HTML
Certain file types can be viewed as HTML in Document Manager. If you are
having problems viewing a document as HTML, refer to the Viewing documents in
HTML topic for a list of supported file types.
Problem: Non-English characters are incorrectly displayed in the
HTML view of a text file
The HTML view of a text file containing non-English characters might display the
non-English characters incorrectly.
Solution: Set the following two properties in the portal_server_root/shared/app/export.cfg file:
v charset: Set this property to the charset of the source (text) file.
v fallbackformat: This property specifies the file format to be assumed in case
the file cannot be identified.
For example, if a text file containing Japanese characters displays the Japanese
characters incorrectly, ensure that the charset property has been set to shiftjis
and the fallbackformat property to FI_SHIFTJIS.
Note: Letting the values of these properties to persist in the export.cfg file may
hinder the correct HTML preview of other files. Thus, it is very important to
revert to the earlier settings of these properties once the text file has been
previewed.
Chapter 1. Troubleshooting 99
Problem: HTML view is displayed in black and white
The HTML view of color files in Powerpoint,, Freelance and Word, displays
grayscale. In Microsoft Word, images are displayed in black and white, while text
is displayed in color.
Solution: The problem lies in starting portal from an XWindows session exported
to a Microsoft Terminal Services session. If the portal is started from an XWindows
session exported to the Windows box directly, full-color images and text are
displayed.
Problem: Stellent does not support comments in Word
documents
If the user creates a Word document with comments and then uses the document
conversion feature to view an HTML version of the document in Document
Manager, text content is visible but comments are not.
This is known limitation of Stellent, which is used in the conversion from Word to
the HTML view format.
Problem: Stellent does not support customized bullet styles
A Word document is created with multiple lines of content, each line using a
different custom bullet style, such as telephone or diamond. The document is
imported into Document Manager and viewed in HTML format. The custom bullet
styles are not preserved in the HTML view.
This is a known limitation of Stellent, which is used in the conversion from Word
to the HTML view format.
Problem: Stellent does not support automatic update functions
in HTML view of a PowerPoint Presentation file
When viewing a PowerPoint presentation file in HTML view, the automatic update
functions in the PowerPoint file do not work. This is a known limitation of Stellent
and is not supported in Stellent’s 8.1 release also.
100 Troubleshooting guide
Limitations viewing documents as HTML
The following issues are expected in the HTML preview of Word and RTF files:
v If the Word document has a diagram with DBCS characters, the characters are shown as
*****.
v Certain fonts like Webdings, Math C and Simsun fonts are not supported.
v When viewing a Word file with tables and text, the order of the content is not the same
as the original.
v Random alignment of text boxes.
v Preview does not display the following font effects found in Word Shadow, Emboss,
Engrave, Double-Strike-Through, Shimmer, or Marching Red Ants.
v Word text effects such as blinking background, dotted underlines, and sparkling text are
not displayed.
v The symbols such as omega, zeta and so on are not displayed.
v Multi-column text will be displayed in a single column.
v Preview does not display table borders, table border colors, styles, agates for DBCS
characters, or page background colors.
v Preview does not display paragraph shading or graphical page borders.
v Vertical text is displayed as horizontal text.
v Diagrams and tables may not be displayed in the same order as in Word file.
v Preview displays a paragraph border as individual borders for each line of the
paragraph.
v Text wrapped around a picture in Word is displayed below the picture.
v Strike-through with small caps may be rendered unevenly.
v Headers and footers in a Word file are not displayed.
v Comments in a Word file are not displayed.
v Table alignment is improper when using Firefox browser.
v Visual Basic controls and macros are not supported.
v WordArt text is displayed as plain text in a frame.
v Picture bullets are not supported.
v Watermarks are not supported.
v Only simple line charts are displayed for Word 2007 files. However, these charts may not
be displayed correctly all the times.
v .png images in a Word 2007 file are not displayed.
v SmartArt in Word 2007 is not supported.
v Automatic table formatting in Word 2007 is not supported.
v Password protection for Word 2007 files is not supported.
v Equations are not supported for Word 2007 files.
v OLE objects do not work.
The following behavior is expected in the HTML preview of a PowerPoint file:
v Chinese characters are not the same as in the original PowerPoint file.
v Comments are lost.
v Only basic line charts are supported.
v Arabic characters are displayed as **** .
v Word art text is displayed as plain text.
v To view DBCS characters, install arialuni.ttf on the server.
v Certain fonts like Monotype Sorts are not supported.
v Smart quotation marks (‘ ’ and “ ”) are incorrectly displayed.
Chapter 1. Troubleshooting 101
Limitations viewing documents as HTML
The following issues can be expected in the HTML preview of an Excel file:
v Drawing objects do not display correctly.
v Different cell borders not displayed.
v Preview doesn’t work for an empty Excel sheet.
v Wrapped text in an Excel file looks different in the HTML preview.
v WordArt text in an Excel file is displayed as plain text.
v ″False″ and ″True″ displayed as 0 and 1, respectively.
v Charts are not displayed properly. For Excel 2007 files, only basic line charts are
displayed.
v Arrows are not displayed properly.
v Comments are lost.
v .png and .gif images are not displayed.
v Date and time format may change.
The following problems are expected in the HTML preview of a Lotus WordPro file:
v On all non-Windows platforms, the HTML preview displays only the text content in the
WordPro file. Font formats, tables, images, DBCS characters, paragraph styles, and
hyperlinks are not displayed.
v Bitmap images, equations, comments, table of authorities, and table of contents are not
displayed.
v Charts are corrupted in the HTML preview.
v Background color is not displayed.
v Patterns are not displayed.
v Shadow and shadow depth are not displayed.
v Page numbers are not appended.
v Multilevel bulleted lists are not displayed properly.
The following behavior is expected in the HTML preview of a Lotus 1-2-3 file:
v A Lotus 123 file containing a map can be uploaded into Document Manager, but when
the document is viewed in HTML, the map is lost.
v Diagrams, including ellipses, rectangles, and free lines, are not displayed.
v Pictures and charts placed in separate cells on the sheet are all displayed in the first cell
of the sheet.
v Horizontal and vertical alignments, justified text, orientation, and merging of two or
more cells are lost.
The following behavior is expected in the HTML preview of a WordPerfect X3 file:
v Text properties, such as Outline and Shadow, are lost.
v Webdings font is not supported when using Mozilla or Firefox browsers.
v Comments are not displayed.
v Drawing objects are lost when viewing the file on Non-Windows platforms. On
Windows, both drawing objects and images are lost.
102 Troubleshooting guide
Limitations viewing documents as HTML
The following behavior is expected in the HTML preview of a Presentations X3 file:
v Hyperlinks do not work.
v OLE objects are not displayed.
v A Microsoft Excel chart embedded in the file is not displayed.
v DBCS characters are lost.
v Bullet styles may be changed because only the following bullet styles are supported :
– Supported Bullets
– Bullets - Basic
– Bullets - Multi Level
– Bullets - Different Characters
– Bullets - Space before bullet Numbering - Types (normal, alphabetic (upper & lower
case), Roman (upper & lower case))
– Numbering - start at any number
– Numbering - prefix (characters before numbering)
– Numbering - suffix (characters after and between levels of numbering)
– Numbering - any number of levels to show
– Bullets - Space between bullet and text
– Numbering - Indents (such as multiple tabs between levels)
The following behavior is expected in the HTML preview of an Open Office Impress file
from Portal 6.0.1 or later:
v Text properties like shadow and contours are lost.
v Hyperlinks do not work.
v Charts and OLE Objects are lost.
v Bullet style may be changed.
v Automatic Update Function is not supported for HTML viewer and searchML
Conversion.
v DBCS characters are displayed as junk characters. Installing arialuni.ttf on the server
may resolve the problem in certain cases.
v Arabic characters are displayed as asterisks (*).
v Botanical font is not supported.
v Viewing a spreadsheet within an Impress file is not supported by Stellent’s VSSOI6 filter.
In addition, viewing the following items in Impress files is not supported:
– OLE (including embedded Impress objects)
– Sound
– Video
– Applet
– Formula
– Chart
– Star Office Draw objects using Effects (Slide Show -> Effects), Interaction (Slide Show
-> Interaction), or Transitions (Slide Show -> Slide Transition)
– Objects
– Floating frame
Chapter 1. Troubleshooting 103
Limitations viewing documents as HTML
The following behavior is expected in the HTML preview of an Open Office Writer file:
v Text properties, such as Outline and Shadow, are lost.
v Drawing objects are lost.
v Bullets may be lost or changed.
v Horizontal lines are lost.
v Spreadsheets are not displayed. In addition, viewing the following items in Writer files is
not supported:
– OLE
– Plug-in
– Sound
– Video
– Applet
– Formula
– Chart
– Star Office Draw objects
Spreadsheet would qualify as OLE.
v The Show Entire Document link does not appear in the Document Manager when
previewing a multi-page Writer file.
The following behavior is expected in the HTML preview of an Open Office Calc file:
v Text only support for Open Office Calc files.
v Plain text only appears in the HTML preview of the file.
v Extra content and interrogation marks (?) display in the HTML preview.
The following behavior is expected in the HTML preview of an Open Office Draw file:
v Text only support for Open Office Draw files.
The following behavior is expected in the HTML preview of a Quattro Pro X3 file:
v There is text only support for Quattro Pro X3 files of versions 9.0 to 12.0. Only plain text
will appear in the HTML preview of the file.
v Bullet style may be changed.
v DBCS characters are displayed as junk characters.
Problems with searching specific language documents
Problem: A user cannot search a specific language document in Document
Manager. When searching for a specific language document, you may encounter
several problems.
Solution:
1. Create the document with the desired language option. Use the basic search on
the same language enabled browser.
2. You do not have to use the same language version browser. Specify the same
language in browser language option or log into a Portal with a user ID that
has the same a preferred language.
Note: You can also use the advanced search with the same language option. For
example, if you search Japanese documents, you have to create the
documents with Japanese language option. Then, you have to search in basic
search on a Japanese enabled browser. You can also use the advanced search
with the Japanese language option selected.
104 Troubleshooting guide
Problems with Document Conversion Services
This section describes the known limitations for Document Conversion Services
(DCS). Some of the limitations require you to perform workarounds.
v On z/Linux, cannot launch setupremotedcs.sh to install DCS remotely
v After adding a document type to the content-type.properties file, have to
re-import existing documents
v Double-byte (DBCS) characters in a document object or diagram display as XXX
in a Microsoft Word document
v The remotedcs.zip. file is seen as having zero bytes by the unzip tool
v When a PDF file is converted from a RTE file, it doesn’t open in Document
Manager
The limitations are related to the IBM proprietary formats being converted to
different types of files. The different types of files that are currently supported by
DCS are given below:
v IBM proprietary formats (Rich Text Editor, SpreadSheet, and Presentation) to
Microsoft/Lotus equivalents.
Note: The Spreadsheet and Presentation Editors are not supported in Portal 6.0
and later.
v Microsoft/Lotus equivalents to IBM proprietary formats (RTE, SpreadSheet, and
Presentation).
v IBM proprietary formats (Rich Text Editor, Spreadsheet, and Presentation) to
HTML/SearchML.
v Open office formats and PDF to SearchML.
v Rich Text Editor to PDF.
v Conversion of over 250 file formats including Microsoft /Lotus /OpenOffice
formats to HTML and SearchML.
Problem: On z/Linux, cannot launch setupremotedcs.sh to install DCS remotely.
On z/Linux you will not be able to launch setupremotedcs.sh as supplied because
it does not contain UNIX end-of-the line characters. When you launch the script it
fails with the message: bad intrerpreter: No such file or directory.
Solution: To resolve this you need to convert the file so it has Unix end-of-line
characters. One possible way to do this: using something like UltraVNC that
supports X11 graphics when working with your Unix system, when you have KDE
installed, open the setupremotedcs.sh file in the kwrite editor. In kwrite, go to
Tools → End of Line. You will see that Windows-DOS is selected as the end-of-line
type. Select the UNIX box instead, then save the file.
Another way to convert end-of-line characters is to use a dos2unix utility that can
change the file format to Unix file format.
Problem: After adding a document type to the content-type.properties file, have
to re-import existing documents.
Solution: If you find that every time you preview a document in a specific format,
you are prompted to download the file, then you need to add or modify the file
Chapter 1. Troubleshooting 105
types in the content-type.properties file. However, for files that already exist in
the document library, you will not be able to preview or convert the documents
until you import them again.
Problem: Double-byte (DBCS) characters in a document object or diagram display
as XXX when a Microsoft Word document is uploaded to Document Manager and
viewed as HTML.
Solution: This is a known limitation that will be fixed in the next portal release.
Problem: You might receive an error when using WinZip to open remotedcs.zip.
The file is seen as having zero bytes by the unzip tool.
Solution: Use an archiving utility other than WinZip, such as unzip.exe.
Problem:When a PDF file is imported or converted from a RTE file and viewed in
Document Manager, it doesn’t open in Document Manager.
Solution:Install the latest version of Adobe Acrobat Reader at client side to view
the PDF files in Document Manager.
Problems with SearchML
Limitations in SearchML
When a Quattro Pro X3 file containing double byte characters (DBCS) is converted to
SearchML, the double byte characters are displayed as junk characters.
When a Quattro Pro X3 file containing numeric data of different font sizes is converted to
SearchML, some of the numbers display additional characters appended to them.
Page number in the Open Office will not be reflected correctly in SearchML, after
conversion.
Double Byte Code Set characters in SearchML are illegible after they are converted from
Open Office-Calc format.
Currency format of financial function in Open Office will not be reflected correctly in
SearchML after conversion.
Header and footer in Open Office will be lost in SearchML after conversion.
Earlier versions of .doc files created with older applications, such as previous versions of
Abiword, may not be converted to SearchML.
PDF files with Chinese characters cannot be converted to SearchML.
Known limitations of Rich Text Editor
This section describes known limitations for the default Rich Text Editor. Some
limitations require that you perform workarounds.
v Pop-up blocker prevents saving documents in the Rich Text Editor
v Images copied from the clipboard into the Rich Text Editor are not visible from
another computer
v Spell Checker fails to start in a cluster environments after the version upgrade
v Remote Spell Checker does not work in an SSL-enabled environment
v Recovering a file from the temporary storage space
v “Using Mozilla, Firefox, or Netscape browsers” on page 108
v Rich Text Editor
106 Troubleshooting guide
v Internet Mail Box
Problem: Pop-up blocker prevents saving documents in the Rich
Text Editor
If you have enabled a pop-up blocker in your browser, you will not be able to save
an edited document when you click the close button (X) in the Rich Text Editor.
Solution: To avoid this problem, add the portal host site to the list of sites where
pop-ups are allowed before you open the document in the rich text editor.
Problem: Images copied from the clipboard into the Rich Text
Editor are not visible from another computer
When creating or editing a document using the Rich Text Editor, if you copy
images from a local application, going through the system clipboard, the images do
not appear if you view the document from another computer. The images are only
visible from the local machine where the copy and paste occurred. This problem
happens because the images are saved with the local URL, and are not saved to
the portal server. When the same document is opened on another computer, the
images are missing since they are not in the location which is stored in the Rich
Text Editor document. This is a known limitation of the Rich Text Editor.
Problem: Spell Checker fails to start in a cluster environment
after the version upgrade
The SpellCheck functionality is not working after installing or uninstalling
WebSphere Portal, and the SystemOut.log shows the exception
448aeb8f ContainerImpl E WSVR0501E: Error creating component null
[class com.ibm.ws.runtime.component.ApplicationMgrImpl]
com.ibm.ws.exception.
RuntimeWarning: Failed to open
/opt/WebSphere/AppServer/config/cells/pvcent44Network/applications/
SpellCheckService.ear/deployments/SpellCheckService at
com.ibm.ws.runtime.component.ApplicationMgrImpl.start(ApplicationMgrImpl.java:246).
Solution: The error occurs because in WebSphere Application Server, during the
installation of an application, there is no way to determine if an application has
been fully expanded and is ready to be started. The APAR PQ97212 solves this
problem. The users can restart the portal server after waiting for 15 minutes. The
exceptions will no longer appear since the application is now been fully expanded
and ready to be started.
Problem: Remote Spell Checker does not work in an
SSL-enabled environment
The remote SpellCheck functionality does not work in an SSL-enabled
environment.
This is a known limitation of the Rich Text Editor.
Problem: Recovering a file from the temporary storage space
While working in a Rich Text Editor file, if the portal session is closed prematurely,
or the browser is closed accidentally before you can publish your file into
Document Manager, it might appear that the file was not saved. However, the file
is available in a temporary storage space, which is located in a path similar to this:
Chapter 1. Troubleshooting 107
app_server_root\profiles\Profile_Name\temp\WAS_Cell_Name\WebSphere_Portal\odc\
RichTextEditor.war\cds\Session_Id\Filename.ort
You can recover your file from the temporary space. If you need help locating your
temporary space, contact your portal administrator.
Note: the document in temporary storage will contain the unpublished content
only if it is has previously been saved by clicking the Save button, or
clicking the close window X in the upper-right corner and then clicking
Save.
Using Mozilla, Firefox, or Netscape browsers
v “Problem: Using spell checker with Firefox browser displays javascript error” on
page 109
v “Problem: Using bold, italic or underline in Mozilla results in blank lines” on
page 109
v “Problem: Bold, italic or underline may function incorrectly in Mozilla” on page
109
v “Problem: Content in Rich Text Editor is not editable when first opened in
browser other than Internet Explorer” on page 109
v “Problem: Focus in editor window instead of Find/Replace window when using
Mozilla” on page 109
v “Problem: Match whole words option not available in Firefox browser” on page
110
v “Problem: No progress window shows when creating or loading a file into the
Rich Text Editor” on page 110
v “Problem: Symbol fonts are not displayed in Mozilla version 1.4, 1.6, and 1.7 and
in Netscape ” on page 110
v “Problem: Symbol fonts are not displayed in Rich Text Editor (RTE) for Mozilla,
Firefox, or Netscape browsers” on page 110
v “Problem: Bullets do not display in Rich Text Editor or HTML view when using
Firefox, Netscape or Mozilla browser” on page 110
v “Problem: Multiple prompts before saving document” on page 111
v “Problem: Comments are not displayed in the HTML view of a Rich Text Editor
file when using Mozilla or Firefox browsers” on page 111
v “Problem: Rich Text Editor closes without saving changes in Netscape browser”
on page 111
v “Problem: Closing the window using the button in the upper right corner” on
page 111
v “Problem: Must select text first to insert a hypertext link” on page 111
v “Problem: Text becomes part of a hyperlink ” on page 112
v “Problem: Alignment doesn’t work for the text with headings that are numbered
or bulleted lists” on page 112
v “Problem: Undo and Redo functions may not work on Comments” on page 112
v “Problem: Bullets and Numbering may function improperly in Mozilla browser”
on page 112
v “Problem: Bullets and Numbering result in loss of paragraph formatting and
right to left text direction in Firefox, Netscape, or Mozilla browser” on page 112
v “Problem: Font drop-down list displays Times as the selected font even if the
browser font is other than the Times font” on page 112
108 Troubleshooting guide
v “Problem: Undo and Redo functions cannot perform character by character text
replacement” on page 112
v “Problem: Undo function does not work after clicking the Print and Toggle
HTML View buttons” on page 113
v “Problem: Toggle HTML View does not function properly in Arabic locale” on
page 113
v “Problem: Incorrect numbering in a multilevel numbered list” on page 113
v “Problem: Alignment of comments cannot be changed in Firefox” on page 113
Problem: Using spell checker with Firefox browser displays
javascript error
When using spell checker in a Firefox browser, a javascript error message may
display. This is due to a Firefox limitation and does not adversely affect the
function or performance of the spell checker.
Problem: Using bold, italic or underline in Mozilla results in
blank lines
When creating a new file using the Rich Text Editor with the Mozilla browser, if
you click bold, italic or underline, and then type text and press Enter to create new
lines of text, a blank line is created on the third line.
Solution: This problem occurs only when using the Mozilla browser. The
suggested fix is to upgrade to the Firefox browser, which does not exhibit this
behavior.
Problem: Bold, italic or underline may function incorrectly in
Mozilla
In a Rich Text Editor file using the Mozilla browser, if you click bold, italic, or
underline and then type text, the applied formatting is reflected. However, if you
then press Enter twice and type some text, the Bold, italic, or underline formatting
applied earlier is lost from that line onwards.
Solution: This problem occurs only when using the Mozilla browser. The
suggested fix is to upgrade to the Firefox browser, which does not exhibit this
behavior.
Problem: Content in Rich Text Editor is not editable when first
opened in browser other than Internet Explorer
When opening or creating content in the Rich Text Editor for the first time in
browsers other than Internet Explorer, such as Mozilla and Netscape, the content
might not be editable. Reopening the Rich Text Editor the second time resolves the
issue.
This is a known limitation for browsers other than Internet Explorer.
Problem: Focus in editor window instead of Find/Replace
window when using Mozilla
When you are editing a Rich Text Editor file using the Mozilla browser, and use
the Find/Replace feature, the focus moves to the editor window after you click the
Chapter 1. Troubleshooting 109
Find or Replace button. To continue using Find/Replace, manually click on the
find/replace window to return the focus to that window.
This is a known limitation of using the Mozilla browser.
Problem: Match whole words option not available in Firefox
browser
If you edit documents using the Rich Text Editor through the Firefox browser, you
will encounter a known limitation when using the Find/Replace function. In the
Find/Replace window, the option to Match whole words when searching content
is not available.
Solution: Use a different browser.
Problem: No progress window shows when creating or loading a
file into the Rich Text Editor
When a rich text file or Internet Mail Box e-mail is created or opened for editing
using Mozilla 1.3, the file will load in a background window until the loading
operation completes. The editor or e-mail window then will appear in the
foreground.
This is a focus issue with Mozilla when both the portlet window and the
application window are refreshing. The focus does not move to the application
window until loading in the portlet window completes.
Solution: Wait for the file to load and the focus will correctly return to the opened
application.
Problem: Symbol fonts are not displayed in Mozilla version 1.4,
1.6, and 1.7 and in Netscape
In the Mozilla browser, versions 1.4, 1.6, and 1.7, and in Netscape, the symbol fonts
such as Wingdings, Wings 3, WP Hebrew David, Monotype Sorts, or Marlett and
so on are not displayed in the Rich Text Editor file.
Problem: Symbol fonts are not displayed in Rich Text Editor
(RTE) for Mozilla, Firefox, or Netscape browsers
Solution: To display the text in Symbol font, do the following:
1. In the Rich Text Editor (RTE), change the font to Symbol.
2. Go to the View Mode.
3. In the View Mode, change the HTML code for the text with Symbol font. For
example, change the following:
<span style="font-family: symbol,fantasy;">Text with the symbol font</span>
To
<span> <font face="symbol,fantasy;">Text with the symbol font</font></span>
4. Go back to the Normal View Mode. The text is changed to Symbol font.
Problem: Bullets do not display in Rich Text Editor or HTML view
when using Firefox, Netscape or Mozilla browser
By default, the Firefox, Netscape or Mozilla browser does not support the
Wingdings font which includes bullet characters.
110 Troubleshooting guide
Solution: The workaround is to set the following options for the browser.
1. Edit the file which sets the encoding of fonts for the browser. The file is called
fontEncoding.properties and is located in the [browser]\res\fonts directory.
By default the full path is [root drive]:\Program Files\[browser]\res\fonts\fontEncoding.properties.
2. Add this line to the font encoding file:
encoding.symbol.ttf = windows-1252 encoding.wingdings.ttf = windows-1252
3. Restart the browser.
This workaround may not be possible for older versions of the browser such as
Netscape 7.2 and Mozilla 1.7.12 or 1.7.13, because the properties files is not
available.
Problem: Multiple prompts before saving document
When using the Mozilla browser in z/OS, users will be prompted with the
message Click OK to continue multiple times when clicking on the X button in
the top right corner of the editor window to close the window and save the
document. This is due to a timing problem with the browser.
Solution: This is a known limitation of the Mozilla browser.
Problem: Comments are not displayed in the HTML view of a
Rich Text Editor file when using Mozilla or Firefox browsers
In Mozilla and Firefox browsers, when you view a Rich Text Editor file (.ort)
containing comments, the comments are not displayed.
Problem: Rich Text Editor closes without saving changes in
Netscape browser
The X button at the lower right-hand corner of the Rich Text Editor window in the
Netscape browser is used to close the window. The window closes without
prompting you to save any unsaved changes.
Solution: Click the X (Close) button provided in the first toolbar of the Rich Text
Editor window.
Problem: Closing the window using the button in the upper right
corner
In Mozilla, if you use the Close button in the upper right-hand corner of the
window to close, you might receive numerous prompts to save.
Solution: Click OK to continue until the prompts no longer appear.
Problem: Must select text first to insert a hypertext link
When inserting a hypertext link into a Rich Text Editor document using Mozilla or
FireFox, you must select some text first, then click on Insert Link to insert the link.
The selected text is used as the content for the hypertext link.
Chapter 1. Troubleshooting 111
Problem: Text becomes part of a hyperlink
When text is entered after a hyperlink in Rich Text Editor’s HTML Toggle view,
using FireFox 1.5 or above and latest Netscape browsers, it becomes part of the
hyperlink.
Problem: Alignment doesn’t work for the text with headings that
are numbered or bulleted lists
When right or center alignment is applied to the text with headings that are
numbered or bulleted lists, using Rich Text Editor in Mozilla, FireFox, or Netscape
browsers, only the text moves to the selected aligned position whereas the bulleted
or the numbered lists remain left aligned.
Problem: Undo and Redo functions may not work on Comments
In Mozilla and Firefox browsers, Undo and Redo functions may not work on
Comments inserted in a Rich Text Editor file.
Problem: Bullets and Numbering may function improperly in
Mozilla browser
In a Rich Text Editor document using Mozilla browser, if you type a few lines of
text with one or more blank lines in between, and try to apply bullets or
numbering to these lines, the last line is not bulleted or numbered.
Solution: Remove the bullets or numbering from the list and then reapply. The
blank lines in between will be deleted and the remaining lines will be properly
bulleted or numbered.
Problem: Bullets and Numbering result in loss of paragraph
formatting and right to left text direction in Firefox, Netscape, or
Mozilla browser
In a Rich Text Editor document using Firefox, Netscape, or Mozilla browser, if you
apply paragraph formatting, including alignment, margins, and spacing on
paragraphs, and then apply bullets or numbering to these paragraphs, the applied
paragraph formatting will be lost.
Also, the right to left (RTL) text direction changes to left to right (LTR) text
direction after applying bullets or numbering.
Problem: Font drop-down list displays Times as the selected font
even if the browser font is other than the Times font
When using Firefox browser, the font settings of the browser override the default
Rich Text Editor font, which is Times. However, the Font drop-down list displays
Times as the selected font even when the user enters the content in the Rich Text
Editor in the browser font.
Problem: Undo and Redo functions cannot perform character by
character text replacement
When using Firefox browser, the Undo and Redo functions cannot perform
character by character replacement in a Rich Text Editor document.
112 Troubleshooting guide
Problem: Undo function does not work after clicking the Print
and Toggle HTML View buttons
When using Firefox browser, the changes made before clicking the Print button or
the Toggle HTML View button cannot be undone by clicking the Undo button.
Problem: Toggle HTML View does not function properly in Arabic
locale
When using Firefox browser in Arabic locale, if you click Toggle HTML View for
the first time, the HTML view is not displayed. Instead, the applied text
formatting, if any, is lost and the text is displayed as a single line of text.
However, this happens only the first time you click Toggle HTML View for an
open Rich Text Editor document. The next time you click Toggle HTML View in
the same document, no new formatting losses occur and the text remains at its
original position.
Problem: Incorrect numbering in a multilevel numbered list
When using Firefox browser, if you use the Increase Indent button to create a
multilevel numbered list, the numbering of the list may not always be correct.
Problem: Alignment of comments cannot be changed in Firefox
When using Firefox browser, you cannot change the default, left alignment of the
comments in a Rich Text Editor document to either right or center alignment.
Rich Text Editor
v Some Latin special characters are not converted correctly in PDF output
v Using Format drop-down menu changes all words in a line of text
v Hyperlinks do not work in edit mode
v Numbers in numbered list do not display correctly
v Cannot cut highlighted text across cells in a table
v Characters with extended formats might be lost
v Double Byte Character Set font specified in WordPro file not reflected
v Cannot save files while in source mode
v Cannot input Chinese (zh_CN and zh_TW) characters using Input Method
Editor in Rich Text Editor
v Receive error message when converting a password-protected file
v Bulleted list must be indented one level
v Quotation marks are not supported in Rich Text Editor
v Mixed mode text direction change is not supported
v The ’Tab’ function to navigate the cells in a table, is not supported
v The alt text is not displayed for image
v Content of the line, at the end of which a page break is inserted, is not visible in
the HTML preview
v Message boxes prompting to save the document in Internet Explorer and Mozilla
Firefox browsers have different interfaces
Chapter 1. Troubleshooting 113
Related to Internet Explorer
v Certain color effects are not reflected when using Microsoft Vista with High
Contrast color schemes enabled
v Indention feature inserts blank lines in addition to tab space
v Choosing the Normal heading in Format inserts HTML tags around lines
v Tab does not indent
v Pressing Enter does not work with the image dialog box
v Cannot select a table to delete
v “Problem: Up or down arrow keys do not function properly in the Format, Font,
or Size drop down lists” on page 121
v Page break inside a table is incorrectly displayed in the HTML preview
v Comments are not inserted if the focus is not in the editing window
v No indication for the selected button on the Accessibility toolbar when switching
between Accessibility toolbar and Rich Text Editor
v Blank lines are inserted above a table when switching between the editing
window and HTML view window
v A blank line is inserted above multiple lines of content when switching between
the editing window and HTML view window
v Disabling bullets and numbering changes text direction from right to left to left
to right
Related to Mozilla or Firefox
v Cannot select a table to delete
v Cannot undo the insertion of a table.
v Problem with deleting characters in a table
v Cannot remove underlining in a table
v Entire list does not bold
v Trouble inserting a URL
v Difficulty cycling through keyboard accessibility functions
v A javascript warning pops up on saving Rich Text Editor document.
v Changing text direction does not work
v Formatting of different paragraph styles in Rich Text Editor is lost when
converted to a PDF
Problem: Some Latin special characters are not converted
correctly in PDF output
When a file created using Rich Text Editor and containing some Latin special
characters is converted to PDF, some of the Latin special characters are unreadable.
The affected languages include Czech, Hungarian, Dutch, Polish, Romanian,
Slovak, Slovenian, and Turkish.
Some of these conversion problems can be attributed to font issues. To support
other languages when a Rich Text Editor file is converted to PDF, font support is
required. However, this font support is currently not available for Rich Text Editor
for all the languages.
114 Troubleshooting guide
Problem: Using Format drop down menu changes all words in a
line of text
In the Rich Text Editor, using the Format drop down menu changes all words in a
line of text regardless of what is selected in the line of text. This is by design.
Solution: If you want to change the text format in part of a line, use the font or
size functions instead.
Problem: Hyperlinks do not work in edit mode
In the Rich Text Editor, when you are editing a document, the hyperlinks do not
work.
Solution: To follow a link, you must be in view mode.
Problem: Cannot cut highlighted text across cells in a table
In the Rich Text Editor, if you highlight text and your cursor crosses the cell
border, even if there is nothing in that cell, when you try to cut the selection, the
highlighted text will not be deleted.
Solution: Reselect the text making sure you do not cross the cell border.
Problem: Characters with extended formats might be lost
In the Rich Text Editor, after you convert a Word document, characters with
extended formats such as the ruby feature might be lost.
Solution: All the features of a native application are available so use a native
editor instead of Rich Text Editor. Select Native Editor on the Document Manager
Edit panel.
Problem: Double Byte Character Set font specified in WordPro
file not reflected
After converting a WordPro document with Document Conversion Services, the
Double Byte Character Set font specified in the WordPro file is not reflected in new
file. The default Rich Text Editor font is applied to all the Double Byte Character
Set characters in the converted file, while font sizes and font styles, such as bold,
are reflected.
Solution: All the features of a native application are available so use a native
editor instead of Rich Text Editor.
Problem: Cannot save files while in source mode
In the Rich Text Editor, if you save a document while in source mode, when you
reopen the document, the source code will display.
Solution: Do not save files while in source mode.
Chapter 1. Troubleshooting 115
Problem: Cannot input Chinese (zh_CN and zh_TW) characters
using Input Method Editor in Rich Text Editor
When you create a new Rich Text Editor file and open for editing, you are not able
to input Chinese characters using Input Method Editor in Rich Text Editor.
Solution: Click any button or selection in the Rich Text Editor interface before you
start the Input Method Editor.
Problem: Garbage characters appear in Traditional Chinese
Even if you have set title and description for simplified Chinese, garbage
characters appear in Traditional Chinese.
Solution: Perform the following steps to correct this problem.
1. Login to portal.
2. Select Administration > Portal Settings > Supported Markups
3. Select HTML.
4. Click on Edit Selected Markups
5. Click on Set locale-specific setting
6. Select Traditional Chinese.
7. Click on Edit setting for selected language
8. Insert UTF-8 as Character Set
9. Confirm the settings.
Problem: A javascript warning pops up on saving the Rich Text
Editor document
In the Rich Text Editor, while saving Rich Text Editor document using Mozilla
browser, a warning window pops up saying Click OK to continue.
Solution: Click OK to resume the saving activity. The RTE Document gets saved.
This is the default behavior of the Mozilla browser. Note: Do not click ’X’ on the
warning window
Problem: Quotation marks are not supported in Rich Text Editor
Quotation marks are not supported in Rich Text Editor on RedHat Linux, pLinux,
zLinux and z/OS on all browsers.
Solution: When using Rich Text Editor On RedHat Linux, pLinux, zLinux and
z/OS, the following characters are not supported in any of the Rich Text Editor
supported browsers:
v Left single quote (’\u2018’)
v Right single quote (’\u2019’)
v Left double Quote (’\u201C’)
v Right double Quote (’\u201D’)
Problem: Mixed mode text direction change is not supported
If the selected text includes both left to right (LTR) text, and right to left (RTL) text,
it is called mixed mode text. In Rich Text Editor, mixed mode text direction change
(LTR or RTL) is not supported.
116 Troubleshooting guide
Solution: Select text with only one kind of text direction, and then click Text
direction left to right or Text direction right to left button.
Problem: The ’Tab’ function to navigate the cells in a table, is not
supported
In Rich Text Editor, if the user presses Tab/Shift+Tab to go to the next cell in a
table, it throws a java script error.
Solution: This function is not supported in Rich Text Editor. You can use the
mouse to click on the desired cell.
Problem: The alt text is not displayed for images
Solution:The users can do one of the following:
v Using the Toggle HTML View from the Task Toolbar in RTE, the alt attribute can
be added to the image (<img>) tags.
v Using the Standard Compliance Check tool in RTE, the alt attributes can be
inserted and appropriate text can be added to the value of the alt attribute.
Problem: Content of the line, at the end of which a page break is
inserted, is not visible in the HTML preview
When you insert a page break at the end of a line in a Rich Text Editor document
and preview the document, the content of that line is not visible.
Solution:Click the Show entire Document link to view the missing content.
Problem: Message boxes prompting to save the document in
Internet Explorer and Mozilla Firefox browsers have different
interfaces
If you enter some content in a Rich Text Editor document and click the Close
button (X) in the upper-right corner of the Rich Text Editor window to close, you
might receive different prompts to save the document in Internet Explorer and
Firefox browsers. Further, the message box in Internet Explorer has buttons with
labels Save and Do not save, while in Firefox, the labels for the corresponding
buttons are OK and Cancel. However, there is no variation in the functionality of
the message boxes displayed in both these browsers.
Limitations in Rich Text Editor
The Paragraph properties box may not display the correct alignment of right to left (RTL)
text.
If you convert a password-protected file into Rich Text Editor file, you will get an error
message. Password-protected file conversion is not supported.
When you create a bulleted list, the list is shifted to the right. If you highlight and press
the Remove Indent button for one item, it deletes that bullet.
In some locales, if you select text for a numbered list, a list of numbers will appear in front
of the text. These numbers will be in Arabic numerals, such as 1, 2, 3, not in the locale’s
numbering system.
Only .jpg and .bmp images can be displayed in Rich Text Editor HTML preview page.
When a RTE file is viewed in HTML preview, some of its content are lost.
Chapter 1. Troubleshooting 117
Limitations in Rich Text Editor
The special characters which are stored in two bytes in Single Byte Character Set languages
can not be converted from Rich Text Editor file to Lotus WordPro.
After converting a password-protected Lotus WordPro file to Rich Text Editor file you will
receive an error message.
The contents of a Rich Text Editor file are not read by the Home Page Reader (HPR) tool.
When a Rich Text Editor file containing text copied and pasted from a document created
using a Word processor, such as Microsoft Word, is converted to a Lotus WordPro,
Microsoft Word, or PDF file, some content and formatting losses occur. However, such
losses do not occur in case of conversion from a Rich Text Editor file containing text copied
and pasted from a simple text editor file, such as a text file created using Notepad.
When a page break is inserted after a line of text other than the last line in a Rich Text
Editor document with multiple lines of content, a blank line is inserted after the page
break.
After converting a Lotus WordPro file to a Rich Text Editor file on Windows, the following
can occur:
v Line length, line style and line width are lost when converting from WordPro to RTE.
v Bitmap images, equations, page breaks, comments, table of authorities and table of
contents are not converted
v A WordPro file with content in a non-English language, such as Arabic, Hebrew, or
Ukranian, displays junk characters in the HTML view and also after conversion to the
Rich Text Editor.
v Headers and footers are not appended.
v Charts are corrupted.
After converting a Rich Text Editor file to a Lotus WordPro file, the following can occur:
v When the symbol font is used for two or more paragraphs, the symbol font is changed
to Arial Black from the second paragraph onwards.
v Varying text indentions created using ″increase indent″ or ″decrease indent″ feature are
changed to a single indention setting in the WordPro file.
v Space between lines and paragraphs is lost.
v Right-alignment of paragraphs is lost.
v Some table cell contents are lost.
v The inserted comments are not displayed.
v Default bullet style changes.
v Images are not reflected.
v Background colors are not reflected.
v Hyperlinks are not reflected.
v Table properties change.
v Double byte character set displays as garbage characters.
v Double byte character set files cannot be converted.
v The page breaks inserted in the RTE file are not appended.
v The text direction changes are not reflected.
v The multiple lines with numbering in table cells appear in a single line.
v The charts are not converted.
v Water mark conversion does not work.
v Blank lines are replaced with asterisks (*).
v Some font attributes may change if the font of text in the Rich Text Editor file was
changed and a table inserted in between the text.
v Horizontal rules are lost.
118 Troubleshooting guide
Limitations in Rich Text Editor
After converting a Microsoft Word file to a Rich Text Editor file, the following can occur:
v Diagrams displayed in reverse order.
v Text direction change is not reflected
v The Symbol font is not supported.
v Single border shows as multiple borders.
v Table border color and background color is not reflected.
v Nested tables do not appear.
v Random alignment of text boxes
v Font effects in Word such as, Shadow, Emboss, Engrave, Double-Strike-Through,
Shimmer and Marching Red Ants are not converted.
v Page breaks and agates for DBCS characters are not reflected in the Rich Text Editor.
v Vertical text is displayed as horizontal text.
v Text wrapped around a picture in Word is displayed below the picture.
v Comments inserted for any text are lost.
v The text alignment of the right or center aligned text cannot be changed in the converted
file. Also, the Paragraph properties box may not display the correct text alignment.
v If you press Enter while editing the converted file, bullets and numbering are lost.
After converting a Rich Text Editor file to a Microsoft Word file, the following can occur:
v Font background color is lost in a table when using the Firefox browser.
v Center alignment in a table is lost when using Internet Explorer or the Firefox browser.
v Hyperlinks are lost.
v Lines are not displayed.
v Sixteen background colors are converted and the remaining colors are changed to the
default white background.
v Bullets, numbering, and table borders are not displayed.
v Page breaks are not appended.
v Only the .jpeg and .png images are displayed.
v A table inserted within another table is removed and its content is displayed vertically in
the outer table.
v Comments are lost.
v Image size reduces.
v Improper text alignment and loss of text color, background color, tables, .jpeg images
and hyperlinks may result, if the RTE file contains content copied and pasted from
Microsoft Word.
v In the Rich Text Editor file, if you selected the text of all the cells of a table and changed
its font, the converted Microsoft Word file will be blank. Selecting the text of each cell
individually and then changing its font in the Rich Text Editor file does not cause this
problem.
v If the font of text in the Rich Text Editor file was changed and a table inserted in
between the text, the original font of the text of the table is not reflected.
v If the Rich Text Editor file contains a table and a hyperlink, the table and its contents
may be lost during conversion, in certain situations.
v Text direction changes are not reflected.
v Some of the blank lines in the Rich Text Editor file are lost.
Chapter 1. Troubleshooting 119
Limitations in Rich Text Editor
After converting a Rich Text Editor file to a PDF file, the following can occur:
v Loss of background color.
v Uneven thickness of table borders.
v Non-Latin characters are displayed as garbage characters.
v Some special characters in Czech, Hungarian, Dutch, Polish, Romanian, Slovak,
Slovenian, and Turkish do not render correctly.
v If there is .bmp image in a Rich Text Editor file, after conversion to PDF, the HTML view
of the PDF is blank. The user cannot view or download the converted PDF file.
v Applied font styles are not reflected exactly as input; instead, all text content is shown in
the same font style.
v Filled circle bullets are displayed instead of numbered bullets.
v A document created with all reserved characters fails to convert, giving the error
message ″An error occurred while trying to convert the document″
v Change in text direction is not reflected.
v Empty rows in tables and blank lines are lost in PDF output.
v Comments are lost in the PDF file.
v The DBCS characters of other languages such as Chinese or Turkish may not be
displayed correctly.
v The .png image files are lost.
v If the font of text in the Rich Text Editor file was changed and a table inserted in
between the text, the lowermost table border is lost.
v The indentation applied to a paragraph of text in the Rich Text Editor file is reflected
only for the first line of the paragraph in the converted file.
After converting a Lotus WordPro file to image, the following can occur:
v Only plain text is displayed in case of non-Windows platforms.
After converting an Open Office Calc file to image, the following can occur:
v Only plain text is displayed.
Related to Internet Explorer
Problem: Certain color effects are not reflected when using
Microsoft Vista with High Contrast color schemes enabled
When using Microsoft Vista and Internet Explorer 7, if you enable High Contrast
color schemes, the following color effects will not be reflected in a Rich Text Editor
file:
v Font color
v Background color
v Color of comments
Solution: The above color effects do get applied but are not displayed in the Rich
Text Editor. Changing the color scheme to non-high contrast schemes will solve the
problem.
Problem: Indention feature inserts blank lines in addition to tab
space
Using the Internet Explorer browser, versions 6 or 7, create a Rich Text Editor file
and add two lines of text. With the cursor at the end of the second line of text,
click the Increase indent button. A tab space is added to the beginning of the line,
120 Troubleshooting guide
as expected, but in addition, a blank line is also inserted. If there are three lines of
text content, and the second line is indented, two blank lines are added, one above
and one below. This is a known limitation of the Rich Text Editor.
Problem: Choosing the Normal heading in Format inserts HTML
tags around lines
In the Rich Text Editor, if you choose Normal for a heading in the Format box, it
will automatically insert HTML tags.
Solution: Switch to source mode and manually edit the HTML.
Problem: Pressing Enter does not work with the image dialog
box
After creating a new Rich Text document, if you use the keyboard sequence of
<Ctrl+Shift+p> to bring up the insert image dialog box, tab to the Browse button
and then press Enter, nothing happens.
Solution: Invoke the Browse button by pressing the space key, not by pressing
Enter.
Problem: Cannot select a table to delete
In the Rich Text Editor, you might find it difficult to select a table so that you can
delete it.
Solution: To delete a table, highlight the surrounding elements and press Delete or
delete the cells one by one.
Problem: Up or down arrow keys do not function properly in the
Format, Font, or Size drop down lists
In Rich Text Editor, after adding texts or paragraphs, the up or down arrow keys
do not function properly in the drop down lists of Format, Font, or Size drop
down lists.
Solution: Use the mouse to select the options in the Format, Font, or Size drop
down lists.
Problem: Page break inside a table is incorrectly displayed in the
HTML preview
When a Rich Text Editor file containing a page break inside a table is previewed,
text similar to <DIV id=pagebreak_49054682437748730 contentEditable=false
style= may be displayed instead of the page break.
Solution: Click the Show entire Document link to view the page break.
Problem: Comments are not inserted if the focus is not in the
editing window
In a Rich Text Editor document, insertion of comments fails with a Javascript error
if the focus is not in the editing window.
Chapter 1. Troubleshooting 121
Solution: Click inside the editing window in the Rich Text Editor and then insert a
comment.
Problem: No indication for the selected button on the
Accessibility toolbar when switching between Accessibility
toolbar and Rich Text Editor
When switching between the Accessibility toolbar and Rich Text Editor windows in
Internet Explorer 6 and 7, it is difficult to determine the selected button on the
Accessibility toolbar, because the dotted box is not displayed around any of the
toolbar buttons.
Solution: To determine the selected button on the Accessibility toolbar, press Tab
and then Shift+Tab. The dotted box is displayed around the selected toolbar
button.
Problem: Blank lines are inserted above a table when switching
between the editing window and HTML view window
In a Rich Text Editor file, if you select the text of all the cells of a table, change its
alignment, and use Toggle HTML View to switch between the HTML view
window and the editing window, blank lines are inserted above the table.
Solution: While changing the alignment of the text of the table, select the text of
each cell individually and then change its alignment.
Problem: A blank line is inserted above multiple lines of content
when switching between the editing window and HTML view
window
In a Rich Text Editor file with multiple lines of content, if you use Toggle HTML
View to switch between the HTML view window and the editing window, a blank
line is inserted above the first line of content.
This is a known limitation of the Rich Text Editor.
Problem: Disabling bullets and numbering changes text direction
from right to left to left to right
When working in right to left text direction in the Rich Text Editor, if you press
Enter twice to end a bulleted or numbered list, the text direction changes to left to
right.
Related to Mozilla or Firefox
Problem: Problem with deleting characters in a table
In the Rich Text Editor, if you hold the Backspace key down, it will delete the
characters in that cell, then the characters in the adjoining cells and then the cells
themselves.
Solution: To delete the entire table from both the HTML source and the Rich Text
Editor, press the delete key again.
122 Troubleshooting guide
Problem: Cannot remove underlining in a table
In the Rich Text Editor, an underline cannot be removed if a table is created within
a table cell. For instance, if you have a table and then create a table within a cell of
the original table that has underlining in it, the new table will also have
underlining in all the cells.
Solution: Select the whole cell again and then click the underline button to remove
the underlining.
Problem: Entire list does not bold
In the Rich Text Editor, if you have a list of items, select them all, and select bold,
the last item does not bold.
Solution: Select the next line, even though it is blank and the last item will become
bold.
Problem: Trouble inserting a URL
In the Rich Text Editor, if you try to insert a URL it looks like nothing is inserted.
Solution: You have to select the text first, then insert the URL. The selected text
will then be associated with the link.
Problem: Difficulty cycling through keyboard accessibility
functions
Due to Mozilla’s implementation of the tab key while in edit mode, you might
have difficulty selecting various keyboard accessible features from the Rich Text
editor.
Solution: If the tab key does not work, try using shift + Tab to select the item you
want.
Problem: Changing text direction does not work
In a Mozilla/Firefox browser, the changing text direction feature may not function
properly in Rich Text Editor, if the selection includes multiple content or even the
whole content.
Solution: Select a single line of text, and then click Text direction left to right or
Text direction right to left button.
Problem: Formatting of different paragraph styles in Rich Text
Editor is lost when converted to a PDF
In Rich Text Editor, paragraphs with different styles are shown as a single
paragraph, when converted to PDF in Mozilla.
Solution: This is a limitation of Mozilla browser. Conversion to a PDF works fine
in Internet Explorer.
Limitations in the Rich Text Editor
On Internet Explorer, if you hit Tab, it does not indent. Instead, the dropdown menus in
the toolbar are highlighted.
Chapter 1. Troubleshooting 123
Limitations in the Rich Text Editor
On Internet Explorer, if you insert a table, you cannot undo that action.
On Mozilla, bold, italic, and underline do not work with CTRL+B, CTRL+I and CTRL+U.
The Cut, Copy, Paste buttons does not appear in the Rich Text Editor tool bar if the editor
is opened using Mozilla browser.
Related to Mozilla or Firefox
Problem: Contents from Rich Text Editor files cannot be copied
to Spreadsheet Editor
The contents from Rich Text Editor files cannot be copied to Spreadsheet Editor in
Mozilla using the menu selection Paste. When any content is copied from Rich Text
Editor documents and pasted on the Spreadsheet Editor in Mozilla, the Paste menu
does not work.
Solution: You need to click on the input bar and press the keys ctrl + v. This
pastes the content into Spreadsheet Editor.
Problem: Using keyboard sequences for copy and paste causes
application failure
If you use Ctrl + C to copy data and Ctrl + V to paste data multiple times, you
might see all the rows of data moved to one cell. In Mozilla, this causes the
application to crash.
Solution: Use the drop-down menu to copy and paste instead of the keyboard
sequences.
Internet Mail Box
v Viewing as HTML
v Colors in charts and graphs change after being e-mailed with Internet Mail Box
v In some locales, title displays garbage characters in Notes e-mail after being sent
via Internet Mail Box
Problem: Viewing as HTML
In Internet Mail Box, there might be some issues with viewing HTML. For
instance,
v Some Double Byte Character Set characters do not display
v Can show fuzzy images and different font sizes
v AutoCAD file does not display correctly
v Some of the text in presentation attachments can overlap
v Text under pictures moves
Limitations
If you e-mail a presentation or a spreadsheet with color charts or graphs using Internet
Mail Box, and then view it as HTML, the colors might change.
In the Korean and other locales, titles that have UTF-8 characters in Notes e-mail, might
display garbage after being sent via Internet Mail Box.
124 Troubleshooting guide
Known limitations of HTML preview
This section describes the known limitations of HTML preview.
Limitations of HTML preview
For most applications, these limitations apply when viewing a file:
v Page breaks are lost in the HTML view.
v A .pcx image type is displayed with an additional header.
These limitations apply when viewing a Word file:
v Nested tables are not displayed.
v A table inserted in a Word file is not displayed.
v When Hebrew is set as the language in Internet Explorer, the file is displayed with the
scroll bar on the right side.
These limitations apply when viewing a Lotus 123 file:
v Unicode characters are missing.
v Hyperlinks are displayed as plain text.
These limitations apply when viewing a Microsoft PowerPoint file:
v Some Ukrainian characters are not displayed.
v Hebrew characters are arranged incorrectly.
v Numbered, alphabetic, and Roman numeral bullets used in a list are displayed as filled
circle bullets.
These limitations apply when viewing an Excel file:
v A chart is displayed as a vertical strip.
These limitations apply when viewing a Lotus Freelance file:
v Bullet sizes are same as in the original file, but bullets are overlapping.
v Arrows are not shown correctly.
v Different bullet styles are not reflected.
v Charts are not displayed.
v Different shapes such as boxes and pyramids within text are displayed as rectangles.
v Different connectors are displayed as straight connectors.
v Text properties such as shadowing and depth are not displayed.
v CorelMEMO objects may not be displayed correctly.
v Unicode characters may not be displayed correctly.
This limitation applies when viewing a Shockwave Flash Object (.swf) file:
v Some of the text may be displayed as junk characters.
Chapter 1. Troubleshooting 125
Limitations of HTML preview
This limitation applies when viewing an MP3 file:
v Some part of the meta-data of the file may be displayed as junk characters.
v You cannot preview an MP3 file that does not contain ID3 tags. Stellent identifies the
following types of ID3 files:
– FI_MP3_ID31 - MP3 file with ID3v1.x metadata
– FI_MP3_ID32 - MP3 file with ID3v2.x metadata
– FI_ID31 - Non-MP3 multimedia file with ID3v1.x metadata
– FI_ID32 - Non-MP3 multimedia file with ID3v2.x metadata
– FI_MP3 - MP3 file with no metadata
– FI_MPGAV1L1 - MPEG-1 audio - Layer 1
– FI_MPGAV1L2 - MPEG-1 audio - Layer 2
– FI_MPGAV2L1 - MPEG-2 audio - Layer 1
– FI_MPGAV2L2 - MPEG-2 audio - Layer 2
– FI_MPGAV2L3 - MPEG-2 audio - Layer 3
Out of these, only the first four file types can be previewed.
This limitation applies when viewing a Yahoo Instant Messenger Archive (.dat) file:
v If the default file name is changed, the file may not display or display junk characters.
The original file name should always be kept intact, i.e., it should be of the form,
yyyymmdd-XXX....dat, where XXX is the id of the local user and the extension of the file
is dat.
Stellent 8.0.1 compatible platforms
The compatible platforms of Stellent 8.0.1 are given in the following table:
Platform Version
Windows (32-bit) Windows NT 4.0 (and above), Windows 95,
Windows 98, Windows 98SE, Windows ME,
Windows 2000, Windows 2003, and
Windows XP
Windows (64-bit) Windows .Net Server 2003 Enterprise
Edition
HP/UX (RISC 32) 11.0 and 11.i
HP/UX (Itanium 64) 11i
IBM AIX (32 with i5/OS) 5.1 - 5.3
i5/OS (OS/400 using PASE) V5R2 or later
Red Hat Linux (x86) Advanced Server 2.1, 3.0 and 4.0
Red Hat Linux (Itanium) Advanced Server 2.1, 3.0 and 4.0
Red Hat Linux (zSeries, 31-bit) 7.2
SuSE Linux (x86) 8.x - 9.x and Enterprise Server 9.0
SuSE Linux (Itanium) Enterprise Server 8
SuSE Linux (zSeries, 31-bit) 7 and 8
Sun Solaris (SPARC) 7.x - 10.x
Sun Solaris (x86) 8.x - 10.x
126 Troubleshooting guide
The Stellent 8.0.1 does not support System p such as AIX/Linux on POWER5 and
z/OS environment.
Known limitations for Document Manager
This section describes known limitations for Document Manager. Some of the
limitations have solutions to help you solve or work around the problem.
v “Problem: Plugin installation shown as unsigned when using Mozilla browser”
on page 128
v Date picker does not work when using Netscape 8.1
v Do not use Display like Internet Explorer option in Netscape 8.1
v An error message is displayed when first opening a Microsoft PowerPoint file
v SQL exception occurs when creating folders deeper than ten levels
v Pagination count of folder content is displayed incorrectly
v Search for documents by author returns no results
v Failure to create a document or folder in Document Manager
v While importing a directory in Document Manager , URLs are reversed in a
second Mozilla or Firefox browser window
v Document Manager temporary filespace could fill up server filesystem
v Importing more than 5000 documents into a document library produces an error
v Executing search may return documents based on the meta-data
v Bulk export of document from Document Manager not supported
v People tag drop-down is cut off by the preview window
v Preview of large document files (10 MB or larger) using Internet Explorer might
take a long time to complete
v To initiate plug-in installation, user must click a white, unlabeled button when
using Netscape 8.1
v Creating a custom Document Manager view fails, or takes an excessively long
time, when using Cloudscape
v Importing files with path longer than the maximum path length fails in
Windows
v Import or export failure messages reported by the Windows Document Manager
plug-in
v A script error message appears when previewing a document using Netscape 8.1
or Mozilla 1.5
v Error message when trying to create a path (subdirectory), or import a file with
a length greater than 180 characters
v Document does not appear in Submitted Drafts view due to long file path
v Portal administrator (wpsadmin) can not restrict access of the owner of a PDM
file or folder
v Some characters cannot be used when naming documents
v Lotus 123 chart displays twice in HTML view
v Colors in charts and graphs change after being e-mailed with Internet Mail Box
v Receive an error when trying to upload a file with Document Manager
v Error Code 00C20206 occurs when more than one user accesses Document
Manager on DB2 for z/OS
v Send a Link is not available when editing a document
v Document Manager does not support Web Services for Remote Portlets
Chapter 1. Troubleshooting 127
v Searching for terms not in the JVM’s locale does not find indexed .html and .txt
documents
Problem: Plugin installation shown as unsigned when using
Mozilla browser
Although the Mozilla browser, version 1.7.13 and higher, is supported for use with
the Document Manager plugin, in the plugin install window, the plugin is shown
as unsigned when using the Mozilla browser. The plugin is shown as unsigned
due to a bug in the Mozilla browser. On other browsers, such as Firefox and
Netscape, the plugin is shown as signed by International Business Machine Corp.
Mozilla as an organization is dropping support for earlier versions of the Mozilla
browser and recommends the use of Firefox or Netscape browsers instead. For
more information, see http://developer.mozilla.org/devnews/index.php/2006/04/12/sunset-announcement-for-fxtb-10x-and-mozilla-suite-17x/.
Problem: Date picker does not work when using Netscape 8.1
When creating a new view in Document Manager using the Creation Date or Last
Modified query criteria, the date picker does not pop up if you are working in the
Netscape 8.1 browser.
This is a known limitation when using this browser.
Problem: Do not use Display like Internet Explorer option in
Netscape 8.1
Using the Display like Internet Explorer option in the Netscape 8.1 browser
disables the Document Manager plug-in functions. Netscape 8.1 does not recognize
installed Internet Explorer plug-ins.
This is a known limitation.
Problem: An error message is displayed when first opening a
Microsoft PowerPoint file
When a Microsoft PowerPoint file is created or opened for the first time in
Document Manager, an error document was not found is displayed. However, the
file is opened and the contents are correct. The error message is not shown when
the file is opened the second or subsequent times.
This is a known limitation of Document Manager.
Problem: SQL exception occurs when creating folders deeper
than ten levels
An SQL exception occurs when creating folders deeper than ten levels within
Document Manager or Personalization with IBM DB2 Universal Database for z/OS
version 7.1 The user may get an error when creating the eleventh-level folder, or be
unable to create documents underneath the eleventh-level folder. The folders or
documents will appear to have been created, but the user will not be able to
successfully navigate to or search for the documents. The logged error message is
SQL0129N The statement contains too many table names. SQLSTATE=54004.
128 Troubleshooting guide
Solution: An attempt should be made to minimize the depth of the hierarchy for
managing content. This is a database limitation when using DB2 for z/OS version
7.1.
Problem: Pagination count of folder content is displayed
incorrectly
If more than ten levels of folders are created in Document Manager with IBM DB2
Universal Database for z/OS version 7.1, the pagination count of the folders is not
displayed correctly starting with the eleventh-level folder. Instead of reading page
11 of X (where X is the total number of folder levels), the pagination count is 1 of
X. The pagination is also incorrect at any folder level beyond the eleventh level.
Also, if the user navigates to the root folder and then back to the eleventh-level
folder, the folder is not visible.
This is a database limitation when using DB2 for z/OS version 7.1.
Problem: Search for documents by author returns no results
When executing a search for documents using the author name as the search
criteria, or when creating a custom document view using the document author or
modifier as view settings, Document Manager returns no search results, even
though there are documents in the library that match the criteria.
Solution: Use lower-case characters when typing the author’s name in a document
search, or when specifying a document author or modifier while creating a custom
document view. If you use the Directory Search Find a Person function to specify
an author, and there are upper-case letters in the author name provided by the
search results, modify the author name to use lower-case letters.
Problem: Failure to create a document or folder in Document
Manager
In Document Manager, the maximum allowed lengths of string fields such as title
and description can vary depending on the language and database. For English
values, all of length limits imposed by the user interface correspond to the
maximum allowed database lengths. However, for other languages such as
Japanese and Chinese that are represented with more than one byte per character
when encoded, the limits imposed by the user interface will be larger than the
allowable number of characters in the database. If a user enters more Japanese or
Chinese characters than allowed by the database, the user will not be able to create
a document or folder in Document Manager.
Solution: To avoid this problem, users might have to enter values shorter than the
maximum input allowed by the user interface.
Problem: While importing a directory in Document Manager ,
URLs are reversed in a second Mozilla or Firefox browser
window
This problem appears if you are using Document Manager and open two Mozilla
or Firefox windows while importing a directory. For example, navigate to the
Document Libraries portlet and click Import page for a document library, then
click Select Directory and Select and Import. In a second Firefox or Mozilla
browser window, enter any URL. The URL is reversed (www.yahoo.com becomes
moc.oohay.www).
Chapter 1. Troubleshooting 129
Solution: This is a known limitation.
Problem: Document Manager temporary filespace could fill up
server filesystem
The Document Manager temporary filespace gradually fills up with temporary
user files. If errors occur and users are not logged out of the portal server during
normal operations, the temporary filespace used by Document Manager to hold
working files for these users might not be cleaned up. Normally this temporary
space is cleaned up when a user logs out of the portal server. The temporary space
is located at portal_server_root/InstalledApps/Document_Manager_xx.ear/pdm.war/temp.
Solution: If there are no users logged into the portal server, it is safe to delete all
subfolders found in the temp directory. These subfolders contain only transient data
and are not needed after a user logs out of the system. Do not delete the files
found in the temp directory (for example, empty.ope), only delete folders found in
the temp directory.
Problem: Importing more than 5000 documents into a document
library produces an error
When importing a large number of documents into a document library, an error
may occur when the number of imported documents is greater than 5000.
Solution: Divide the import process into several steps so that each import contains
less than 5000 documents.
Problem: Executing search may return documents based on the
meta-data
Meta-data for documents is also indexed for search and executing a search may
return documents that do not appear to match the search criteria. This is because
the meta-data matched the search criteria.
Solution: There is no workaround to this problem.
Problem: Bulk export of document from Document Manager not
supported
Document Manager and Document Libraries do not support exporting multiple
documents in one action (bulk export).
Solution: This is a known limitation.
Problem: People tag drop-down is cut off by the preview window
Using Document Manager with Internet Explorer, if you click on a movie file, such
as an AVI or MPEG file, a document preview is provided using a helper
application from your local system. The helper application window pops up to ask
if you want to save or open the file. If you click Open, the helper application plays
the movie in a preview window. Once this window is displayed, if you click the
people tag drop-down to see the Last modified by information, the bottom portion
of the people tag drop-down is cut off by the preview window, whether there is a
movie playing there or not.
130 Troubleshooting guide
Solution: This is a known limitation.
Problem: Preview of large document files (10 MB or larger) using
Internet Explorer might take a long time to complete
If you preview a document that is 10 MB in size or larger, the Internet Explorer
browser might seem to lock up because the preview operation can take 4 or 5
minutes to complete. This is a known limitation of using Document Manager with
Internet Explorer.
Problem: To initiate plug-in installation, user must click a white,
unlabeled button when using Netscape 8.1
When using Document Manager in the Netscape 8.1 browser, the Install Missing
plug-in button is shown as a white, unlabeled button. This occurs on Document
Manager pages which require the plug-in, such as the document library view, edit
a document, or in the Document Libraries portlet.
Solution: Click the white, unlabeled button to display the Install Missing plug-in
button in the toolbar. This is a known limitation of using Document Manager with
Netscape 8.1.
Problem: Creating a custom Document Manager view fails, or
takes an excessively long time, when using Cloudscape
When creating a custom view in Document Manager, if you specify a
multiple-word title search with the All words option selected, the view creation
process might fail, or take an excessively long time to respond. This problem
occurs when Cloudscape is the portal database.
Solution: Use the search function rather than creating a custom view to perform
multiple-word title searches for Document Manager content. You can also
configure the portal to use a different database, such as DB2 or Oracle.
Problem: Importing files with path longer than the maximum path
length fails in Windows
Windows has restrictions on the maximum path length allowed for a file. This
limit is not known to Document Manager ahead of time. When importing files
from Document Manager to your local machine, if the file path is longer than the
acceptable Windows maximum path length, then the file import will fail with an
error such as:
Could not download document to file filename. Error code error code.
More explanation of the error codes can be found at the Microsoft Web site:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/system_error_codes.asp.
Problem: Import or export failure messages reported by the
Windows Document Manager plug-in
When using a Windows-based local system to import or export documents from
Document Manager, the import or export might fail, and the plug-in will display
an error as a result. If the error contains an error code, you can find more
information about the exact cause of the error at the following Microsoft Web page:
Chapter 1. Troubleshooting 131
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/system_error_codes.asp.
Problem: A script error message appears when previewing large
documents using Netscape 8.1 or Mozilla 1.5
When previewing a large document using Document Manager and the Netscape
8.1 or Mozilla 1.5 browser, a script error message window may appear, even
though the document is successful previewed.
The problem occurs because the Javascript timeout is set to 5 in Netscape 8.1,
which uses Gecko/20060127. The timeout is also set to 5 in Mozilla 1.5, which uses
Gecko/20060111. However, Mozilla doesn’t seem to obey this option. A
workaround is to set the dom.max_script_run_time variable to zero (0) to allow
documents larger than 2.5 MB to be downloaded.
Problem: Error message when trying to create a path
(subdirectory), or import a file with a length greater than 180
characters
An error message is displayed when the user tries to create a path (subdirectory)
with a length greater than 180 characters in Document Manager. The same error
occurs if the user tries to import a file into Document Manager when the name of
the file is more than 180 characters.
The workaround is to choose a path (subdirectory) name or file name with a
length less than 180 characters.
Problem: Document does not appear in Submitted Drafts view
due to long file path
There are limitations on the overall length of the file path for a document, which
includes all folder (directory) names containing the document, plus the file name
of the document. The maximum path length allowed in Document Manager is 1000
characters for documents not involved in workflows and 200 for any documents
that are involved in workflows. For example, if you create a workflow folder path
of 180 characters in length, then a document name of 25 characters, the document
is placed in the draft folder instead of the submitted folder, indicating that
workflow is broken. If the folder path alone exceeds the 200 character limit, you
will not be able to create a document within the workflow. There are several
additional folder and file name path length limitations imposed by other
components. Due to operating system limitations, creating paths greater than 180
characters in length will cause problems with any operations that interact with the
file system, such as roundtrip editing. Also, paths greater than 300 characters
(including file name) will cause navigation problems in Internet Explorer as these
paths exceed the maximum allowed URL size.
Problem: Portal administrator (wpsadmin) can not restrict access
of the owner of a PDM file or folder
This is working as designed. There is no way to restrict access for an author of a
document.
132 Troubleshooting guide
Problem: Some characters cannot be used when naming
documents
You can create document names using non-Latin characters (such as Japanese and
Cyrillic). However, some characters are invalid, such as asterisks (*), question
marks (?), greater than and less than signs (< >), percent signs (%), at signs (@),
forward and backward slashes (/ \), apostrophes (’), double quotes (″), pipes (|),
colons (:), and square brackets ([ or ]). You receive an error message when trying
use a name with these characters. Document names can contain spaces but cannot
be the same as an existing document name.
Problem: Lotus 123 chart displays twice in HTML view
If you upload a Lotus 123 document to Document Manager in which you have
created a chart of any type (for example, line, area, or pie), you might find the
HTML view of the document (viewed by clicking on the file name link) displays
the chart twice, once within a cell and again below the sheet area.
Comments: This issue will be fixed in a future release.
Problem: Colors in charts and graphs change after being
e-mailed with Internet Mail Box
If you e-mail a presentation with color charts or graphs, and then view it as
HTML, the colors might change.
Problem: Receive an error when trying to upload a file with
Document Manager
If you try to upload a file or create a document and receive an error message
similar to:
Error creating new document! - resourceNotFound,
your Web server might not be configured to receive HTTP PUT requests or if you
use a proxy server, that might not be configured to receive HTTP PUT requests.
Solution: Configure your Web Server to allow HTTP PUT requests. If you use a
proxy server, also configure proxy server to allow HTTP PUT requests.
Problem: Error Code 00C20206 occurs when more than one user
accesses Document Manager on DB2 for z/OS
Solution:
v Follow the recovery instructions from DB2 for z/OS Messages and Codes and
the recovery instructions in the PTF.
v Install DB2 for z/OS PTF UQ83393 on the DB2 system.
v Run the initial product loader (IPL).
Problem: Send a Link is not available when editing a document
When editing a document, the Send a Link option does not appear on the More
Actions menu. Save the file and then click on the file name to go to the read view
of the document. From the read panel, you will be able to click More Actions and
then Send a Link.
Chapter 1. Troubleshooting 133
Problem: Document Manager does not support Web Services for
Remote Portlets (WSRP)
An exception occurs when trying to use Document Manager through WSRP.
Problem: Searching for terms not in the JVM’s locale does not
find indexed .html and .txt documents
HTML and text documents are indexed using the JVM’s locale and not according
to the encoding of the document. Searching for terms not in the JVM’s locale does
not find indexed .html and .txt documents. For instance, if the system is running
an English locale, a DBCS HTML document will be indexed using an English
codepage. Searching with a DBCS term will not find the HTML file.
Known limitations for Document Libraries
v “Enabling workflow fails due to large number of groups”
v “Authentication errors occur for document import tasks that run longer than
two hours”
v “Importing a file using Document Libraries may fail because of an existing file
with the same name”
v “Create document library fails due to number of groups” on page 135
Enabling workflow fails due to large number of groups
Problem: If the number of groups is larger than the maximumSearchResults value in
the wmm.xml file, then you will not be able to enable workflow. The message ″The
number of groups are more than supported.″ is displayed. Also, the Approvers box
under Approvals Workflow is empty.
Solution: To work around this error, edit the wmm.xml file and change the default
setting maximumSearchResults="200" to maximumSearchResults="300". You can set
the maximumSearchResults value to greater than 300 if needed.
Authentication errors occur for document import tasks that run
longer than two hours
Problem: Authentication errors occur for document import tasks that run longer
than two hours When importing large numbers of documents into a document
library using the Document Libraries portlet, if the import takes longer than two
hours, authentication errors (HTTP 401 errors) can occur.
Solution: The LTPA token that is used during the Document Libraries import task
has expired before the import task has completed. By default this value is set to
two hours. When doing large document imports that can take longer than the
value set for the LTPA token timeout, increase the LTPA token timeout to a value
that allows the import job to complete. The LTPA token timeout setting can be
found and set in the administration console (Authentication Mechanisms >
Timeout under the LTPA section).
Importing a file using Document Libraries may fail because of an
existing file with the same name
Problem: When importing a file using Document Libraries, if a locked document
with the same file name already exists in the target document library, the import
fails. While trying to import the file, the portal shows the error ″The following
134 Troubleshooting guide
document already exists in this library, do you wish to overwrite?″ but if you click
Yes, rather than successfully overwriting the existing file, the import fails with the
message ″A document with the same name already exists and you do not have
permission to replace it.″
Solution: This is a known limitation of this release. You can change the name of
the file you wish to import to work around the problem.
Create document library fails due to number of groups
Problem: When creating a document library, if LDAP security is enabled, and there
are a large number of users (more than 300), the create document library function
might fail with the message ″The number of groups are more than supported.″
Solution: To work around this error, edit the wmm.xml file and change the default
setting maximumSearchResults="200" to maximumSearchResults="300".
Known limitations for desktop components
v “A reviewer cannot edit a submitted draft using desktop components”
v “Documents cannot be copied using drag and drop in the right-hand panel of
Windows Explorer”
v “Cannot copy a folder using desktop components” on page 136
v “Folders and files are copied instead of moved after drag and drop” on page 136
v “Cancel does not stop draft submission” on page 136
v “Drag and drop of a folder containing documents or subfolders may not copy
children” on page 136
v “Do not use an IPv6 (Internet Protocol Version 6) Web address with desktop
components” on page 136
v “Desktop components does not reflect changed document library settings” on
page 137
v “Dragging or copying a folder from desktop components to a local drive does
not work correctly” on page 137
A reviewer cannot edit a submitted draft using desktop
components
When document approval workflow is enabled for a document, the author of the
document can submit the document for approval using desktop components.
However, if another user, such as a document reviewer, tries to edit the submitted
draft using desktop components, an error message is displayed, and the file is not
editable. When submitted for approval, the document is set to read-only mode, so
is not editable by reviewers using desktop components.
Solution: Edit the document using Document Manager through Portal.
Documents cannot be copied using drag and drop in the
right-hand panel of Windows Explorer
Using desktop components with Windows Explorer, you can drag and drop
documents from the right-hand panel of Explorer and copy them into any folder
that is visible in the left-hand panel of Explorer under Document Manager.
However, if you attempt to drag an drop documents from one folder in the
Chapter 1. Troubleshooting 135
right-hand panel to another folder in the right-hand panel, an error is displayed:
source and target folders are the same .copy cancelled. The documents are
not copied.
Solution: This is a known limitation of desktop components.
Cannot copy a folder using desktop components
When you right-click on a library folder using desktop components, the context
menu shows several options for working with the folder, but the Copy option is
not active, because copying a folder is not supported for desktop components. This
is a known limitation.
Folders and files are copied instead of moved after drag and
drop
If you use desktop components to drag and drop a folder or files within a library,
the items are copied instead of moved. Usually, when you drag and drop within a
library, the items are moved instead of copied.
Solution: Moving items using desktop components is not supported. To move
items within a library, use the full portal library interface instead of desktop
components.
Cancel does not stop draft submission
When workflow is enabled for a document library, you can submit a draft for
approval using desktop components. If you create a Private Draft document, then
right-click on that document from Windows Explorer and choose Submit Draft, a
window is displayed with a Cancel button. However, by clicking Submit Draft,
you have already issued the command to the server to put the document into the
workflow (draft approval) process, so the Cancel button does not cause the draft
submission process to stop.
This is a known limitation.
Drag and drop of a folder containing documents or subfolders
may not copy children
When using drag and drop from desktop components to copy a folder with child
documents (or subfolders) from Windows Explorer into a library, the children in
the folder (documents or subfolders) might not be copied correctly.
Solution: This is a known limitation of desktop components. The workaround is to
copy the documents, or subfolders, one at a time using drag and drop.
Do not use an IPv6 (Internet Protocol Version 6) Web address
with desktop components
During desktop component configuration, if you use an IPv6 URL (Web address)
in the Document Manager Server URL field, the URL does not work correctly and
an error message is displayed. An IPv6 URL looks like this: http://[2002:92a:8f7a:20:9:42:81:231]:10038/wps/desktop.
Solution: Use an IPv4 URL instead (example: http://yourserver.yourco.com:10038/wps/desktop).
136 Troubleshooting guide
Desktop components does not reflect changed document library
settings
When document library settings are changed, such as enabling or disabling
workflow or document locking, you must remove the document library and re-add
the library so that desktop components can pick up the new settings. No data is
lost when removing and re-adding a document library.
Dragging or copying a folder from desktop components to a
local drive does not work correctly
Dragging or copying a folder from a Document Manager directory in the desktop
components section of Windows Explorer to a local system drive (such as C:) does
not copy the folder structure correctly.
Solution: This is a limitation in the design of desktop components. You can copy
or drag files directly from Document Manager in your browser to a local directory,
so you should use this option instead. Before copying, ensure that a file with the
same name does not already exist on the local drive.
Search fails and DB2 encounters errors with message 00C90096
Problem: When Document Manager and Web Content Management are heavily
loaded, you may see the following error when building the search index. This error
results in search not working in Document Manager or Web Content Management.
FunctionName: com.ibm.icm.ts.tss.app.IndexMaintainer.handleError [java.lang.ThreadGroup[name=icmciWorkManager: icmjcrear,maxpri=10]]: error processing pending event name:
tamp=’2006-11-18 01:29:52.647556’, document id=<workspace: 1, itemid: AB001001N06K17C005000003E0>’, parentID: <workspace: 1, itemid: AB001001N06K17C004000002E0>
SourceId: com.ibm.icm.ts.tss.JCRCFLLoggerImpl
Category: SEVERE
ExtendedMessage: com.ibm.icm.ts.tss.ls.DatabaseException: com.ibm.db2.jcc.t2zos.y: [IBM/DB2][T2zos/2.10.44]T2zosStatement.readExecuteImmediate:nativeExecuteImmediate:807 at com.ibm.icm.ts.tss.app.IndexMaintainer.reindexWorkspace(IndexMaintainer.java:338)
at com.ibm.icm.ts.tss.app.IndexMaintainer.processPendingUpdates(IndexMaintainer.java:201)
at com.ibm.icm.ts.tss.app.IndexMaintainer.runIndexMaintenance(IndexMaintainer.java:137)
Solution: In DB2, run the following command:
select count(*) from <jcrdb>.ICMSTJCRTSPATHINFO WHERE INDEXID=1;
Write down the returned count, <spath_count>. Increase NUMLKUS in the DB2
zParms to <spath_count>+20000. Restart DB2 and WebSphere Portal and rebuild
the search index.
Note: When running a data-sharing DB2 environment, the lock structure storage
should also be increased to accommodate the increased NUMLKUS setting.
Troubleshooting Personalization
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic. For troubleshooting installation problems, refer to the pzninstall.log file in
the temp directory. For uninstallation, refer to temp/pznuninstall.log.
v “Problem: MovieSite installation fails on LikeMinds database” on page 138
v “Problem: LikeMinds does not run with j2ee 1.2” on page 138
Chapter 1. Troubleshooting 137
v “Problem: The menus in the Personalization Navigator portlet do not appear
when their menu launcher is clicked”
v “Problem: Security message is repeatedly displayed when creating or editing a
rule”
v “Problem: Personalization will no longer open documents from Document
Manager” on page 139
v “Problem: A rule does not return the correct resources” on page 139
v “Problem: LikeMinds recommendation rules do not return instances of
CmResource” on page 139
v “Problem: There are broken links in Personalization” on page 140
v “Problem: Personalization Navigator is empty” on page 140
v “Problem: Personalization rule events may not fire in the Rational Unit Test
Environment.” on page 140
v “Problem: Smart delete does not work for folders” on page 141
v “Problem: Personalization authoring portlets do not support Parallel Portlet
Rendering” on page 141
Problem: MovieSite installation fails on LikeMinds database
In order to install MovieSite, you must have an unused LikeMinds database. Once
LikeMinds is installed and running, trying to install MovieSite will return sql
errors because users with conflicting IDs will already be present in the database.
Solution: Either remove all contents of the LikeMinds database on which you are
attempting to install MovieSite, or create a new LikeMinds database.
Problem: LikeMinds does not run with j2ee 1.2
By default, LikeMinds code uses the datasource named jdbc/lmDS to connect to its
database. This is a 5.0 datasource, and cannot be used by j2ee 1.2 applications.
Solution: In order to use LikeMinds with a j2ee 1.2 application, create a 4.0
datasource pointing to the LikeMinds database, and set the system property
lm.db.dsname to the name of the 4.0 datasource.
Problem: The menus in the Personalization Navigator portlet do
not appear when their menu launcher is clicked
Solution: If you click the New or More Actions menu launcher and the menu does
not appear, you might need to click your primary mouse button somewhere else in
the page (other than the menu launchers) before clicking on the menu again.
Clicking the left mouse button on any non-link or non-button element (such as
empty areas of the browser window or in regular text) will reactivate the menu.
This only occurs when one of the menus is open and the other menu launcher is
clicked.
Problem: Security message is repeatedly displayed when
creating or editing a rule
When SSL is enabled in Internet Explorer, creating a new rule or editing an
existing rule may display a message which says ″This page contains both secure
and nonsecure items. Do you want to display the nonsecure items?″ This is a
known defect with Internet Explorer that falsely indicates the page is not secure.
138 Troubleshooting guide
Solution: There are two possible solutions.
v You may choose yes or no. Neither choice will send sensitive information over a
connection which is not secure. If you choose no, you may momentarily see an
error page before the rule editor is displayed.
v You can disable the warning by completing the following steps (in Internet
Explorer):
1. Select Tools from the menu.
2. Under Tools, select Internet Options.
3. On the Security tab, determine the appropriate zone for your WebSphere
Portal site.
Note: Consult the Internet Explorer documentation for more information
about how websites are classified into zones.
4. Select the appropriate zone, and then click the Custom Level button.
5. In the Settings dialog, scroll down until you see the Miscellaneous category.
Under the ″Display mixed content″ option, select the radio button Enable.
6. Click OK to save your changes. The warning will no longer be displayed.
Problem: Personalization will no longer open documents from
Document Manager
If the context root of the server running WebSphere Portal is changed after any
user has visited Document Manager, a Document Manager administrator must
re-enable the ability to open Document Manager documents from Personalization.
Solution: The Document Manager administrator must perform the following steps
to re-enable linking:
1. Enter the Document Manager configuration mode for the document library
containing the documents you wish to link to. Disable Search Center
registration and submit your changes.
2. Enter the configuration mode again and re-enable Search Center registration.
Problem: A rule does not return the correct resources
A rule that uses the Folder path or Name attribute of a CmResource does not
always return the correct resources. Specifically, if the rule contains a mixture of OR
and AND operations with Folder path or Name attributes, incorrect results may be
returned. The problem will be fixed in a future release.
Using the AND operator between Folder path or Name will either result in no
results, or in some cases cause an exception to be thrown. Since an object can only
have one name and one path, an object can never be in one path AND another path
or have one name AND another name.
Problem: LikeMinds recommendation rules do not return
instances of CmResource
Running LikeMinds recommendations rules to return instances of CmResource is
not supported in this release. Support will be provided in a future release.
Chapter 1. Troubleshooting 139
Problem: There are broken links in Personalization
In many places in the user interface, Personalization will let you know when there
are broken links. For instance, when a rule mapping references a rule that has been
deleted, a red X displays next to the rule name when viewing the rule mapping. In
some places, such as inside of a rule, references which are broken do not currently
display the broken link indicator. When changing the name of an artifact, or when
changing the session key of an application object, it may be necessary to edit all
artifacts which reference that object in order to correct the links.
Solution: In some cases, as when an artifact is simply moved, opening the editor
and resaving is all you will need to do to fix a broken link. In other cases, such as
inside the rule editor or when an item is deleted, you may need to bring up the
appropriate sub-dialog, such as the resource.attribute dialog, and reselect the
appropriate item.
Problem: Personalization Navigator is empty
This issue might be a problem on Linux platforms.
Solution: The number of file handles might need to be increased.
1. Open a command prompt and enter ulimit -n 4096.
2. Stop and restart WebSphere Portal .
Problem: Personalization rule events may not fire in the Rational
Unit Test Environment.
When using the Portal Unit Test Environment, Personalization rule events may fail
to fire.
Solution: There may be an error in the logs for the test environment:
[3/7/05 13:33:00:174 CST] 5b171091 EJBContainerI I WSVR0207I: Preparing to start EJB jar:
pznscheduler.jar
[3/7/05 13:33:00:199 CST] 5b171091 BeanMetaData E CNTR0075E: The user-provided class
"com.ibm.websphere.startupservice.EJSRemoteStatelessPznSchedulerInitializerBeanHome_
92051795"
needed by the EnterpriseBean could not be found or loaded.
[3/7/05 13:33:00:212 CST] 5b171091 EJBContainerI E WSVR0209E: Unable to prepare EJB jar
pznscheduler.jar [class com.ibm.ws.runtime.component.DeployedModuleImpl], enterprise
bean com.ibm.etools.ejb.impl.SessionImpl(PznSchedulerInitializerBean) (transactionType:
Bean, sessionType: Stateless)
java.lang.NoClassDefFoundError: Error while defining class:
com.ibm.websphere.startupservice.EJSRemoteStatelessPznSchedulerInitializerBeanHome_92051795
This error indicates that the class:
com.ibm.websphere.startupservice.AppStartUpHome could not be located while
defining the class:
com.ibm.websphere.startupservice.EJSRemoteStatelessPznSchedulerInitializerBeanHome_92051795
. This is often caused by having the class at a higher point in the classloader
hierarchy.
To eliminate the error, the pznscheduler.ear may be uninstalled.
140 Troubleshooting guide
Problem: Smart delete does not work for folders
If a folder is deleted on the authoring server using the smart delete mode, the
same folder in the publish server is not deleted. The children of the folder are
deleted on the publish server, unless they are sub-folders.
Solution: This is a permanent restriction.
Problem: Personalization authoring portlets do not support
Parallel Portlet Rendering
Using Parallel Portlet Rendering on the Personalization authoring
portletsPersonalization Navigator and Personalization Editor can generate
database-related exceptions because they do not support Parallel Portlet Rendering.
You may get an exception similar to the following:
com.ibm.icm.ci.data.impl.dautils.PLockNode _executeJCRLock DSRA9110E: Connection is closed.
com.ibm.websphere.ce.cm.ObjectClosedException: DSRA9110E: Connection is closed.
.
.
.
com.ibm.websphere.personalization.ui.managers.PznAuthoringRepositoryManager.
isLocked(PznAuthoringRepositoryManager.java:393)com.ibm.websphere.personalization.
ui.managers.AbstractArtifactManager.isLocked
(AbstractArtifactManager.java:370)
com.ibm.websphere.personalization.ui.details.views.item.PznArtifactItemHandler.canEdit
(PznArtifactItemHandler.java:156)
Solution: Disable Parallel Portlet Rendering for these two portlets. This should not
impact performance of the Personalization runtime portlet Personalized List.
Parallel Portlet Rendering is intended to be used for runtime portlets. Perform the
following steps to disable Parallel Portlet Rendering for the Personalization
Navigator and Personalization Editor:
1. Select Portal Administration → Portlet Management → Portlets.
2. Search for the Personalization Navigator and Personalization Editor portlets.
3. For each, select the Configure portlet icon.
4. Ensure the Enable parallel rendering check box is unchecked.
5. Click OK to save your settings.
Troubleshooting portal design
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Recovering from a faulty theme” on page 142
v “Administrative portlets fail on pages that use customized themes” on page 142
v “Preview page does not display” on page 142
v “Garbage words may be displayed in portlet page” on page 142
v “You cannot search for a portlet in a language other than English” on page 143
v “Formatting and JavaScript problems in rendered Portal page” on page 143
v “JSP does not compile when using drag and drop (dnd) tags” on page 143
Chapter 1. Troubleshooting 141
Recovering from a faulty theme
If the portal is configured to use a theme that contains errors, the affected portal
pages might not display or might display incorrectly. To avoid this problem, be
sure to test and debug a theme before it is used on the portal. If a faulty theme is
installed, perform the following procedure to remove it from the system:
1. Stop WebSphere Portal.
2. Delete the subdirectory for the faulty theme. The root directory for themes is
located in the WebSphere Application Server directory.
v z/OS: was_profile_root/installedApps/cellname/wps.ear/wps.war/themes/
The themes folder contains a subdirectory for each markup type. The faulty
theme would be in a folder below one of the markup-type subdirectories.
3. Start WebSphere Portal.
4. Log in to the portal as administrator.
5. Click Administration.
6. Click Portal User Interface.
7. Click Themes and Skins.
8. Delete the faulty theme.
Administrative portlets fail on pages that use customized themes
Problem: When one of the administrative portlets is placed on a page with a
customized theme, or a customized theme has been applied to the portal
administrative pages, the portlet could fail with a null pointer exception written to
the log file. This problem can also occur if the portlet is launched in a new
window that uses the customized theme.
Cause: The administrative portlet requires certain request parameters for
processing. These parameters are made available to the portlet using the
<portal:adminNavHelper/> tag.
Solution: If you need to use an administrative portlet with a customized theme,
edit the parent page of the theme, typically Default.jsp, and add the following
lines:
<%@ taglib uri="/WEB-INF/tld/portal-internal.tld" prefix="wps" %>
<portal:adminNavHelper/>
You should also make the same changes to Plain.jsp for the theme. This file can
be used to open portlets in a new window.
Preview page does not display
Problem: If a user is setting the theme for a page or the skin for a portlet, the
preview icon does not work if the theme or skin directory name contains double
byte character set (DBCS) characters.
Solution: This is a current limitation. To avoid this problem, do not use DBCS
characters in the directory name for new themes and skins.
Garbage words may be displayed in portlet page
Problem: If a user changes the browser language, some garbage words may be
displayed in the portlet page.
142 Troubleshooting guide
Cause: Some strings are cached in the session for performance reasons and will
only change when the session is re-created (usually during login). This can occur
in all languages and will vary from portlet to portlet since caching requirements
also vary.
Solution: This is a current limitation. Log out then log back in to solve the
problem.
You cannot search for a portlet in a language other than English
Problem: When you are navigating a portal using a language other than English,
you cannot search for the portlet from the portlet list.
Solution: Set the portlet name using the specific language for this portlet. Portlet
management will use the portlet name in the browser language to search for the
portlet. This is a current limitation.
Formatting and JavaScript problems in rendered Portal page
Problem: Formatting problems and JavaScript console errors and warnings occur
when a page is rendering. Formatting problems may include such things as excess
white space, alignment issues, and truncation. These problems may occur due to
inconsistencies in the way different browsers render markup as well as differences
due to the DocType specified for the page. This can be a particular problem when a
″strict″ DocType is specified but the markup is created based on an older
″transitional″ (″quirks″ mode) DocType.
Solution: Ensure that theme and portlet output are consistent with the DocType
specified by the theme the page uses. Either set the theme to use a different
DocType or update the rendered markup to be compatible with the selected
DocType.
JSP does not compile when using drag and drop (dnd) tags
Problem:If you wrap conditional Java scriplet code around drag and drop tags, it
will not compile the JSP correctly. The tags affected are <dnd:drag>, <dnd:drop>
and <dnd:dragHandle>.
Example: This is an example of wrapping conditional scriplet around <dnd:drop>.
This code will not compile.
<dnd:drag namespace="wp" type="content" value="value" multiselectable="true">
<div style="display: inline;">
<%
if( isContentItem() )
{
%><dnd:drop namespace="wp" type="content" name="wp.item1" action="<%= dndLink %>" supportsMultiselect="true" multiselectDelimiter="&"><%
}
%><img border="0" src="<%= imageLink %>" alt="Example Image" title="Example Image"><%
if( isContentItem() )
{
%></img></dnd:drop><%
}
%></div>
</dnd:drag></dnd:drop>
Solution: Use a conditional statement like this:
Chapter 1. Troubleshooting 143
<% if( isContentItem() ){ %>
<dnd:drag namespace="wp" type="content" value="value" multiselectable="true">
<div style="display: inline;">
<dnd:drop namespace="wp" type="content" name="wp.item1" action="<%= dndLink %>" supportsMultiselect="true" multiselectDelimiter="&">
<img border="0" src="<%= imageLink %>" alt="Example Image" title="Example Image">
</img></dnd:drop>
</div>
</dnd:drag>
<% }else{ %>
<dnd:drag namespace="wp" type="content" value="value" multiselectable="true">
<div style="display: inline;">
<img border="0" src="<%= imageLink %>" alt="Example Image" title="Example Image">
</img></div>
</dnd:drag>
<% } %>
Troubleshooting portlet development
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Login command customization fails”
v “Struts portlets from the IBM Workplace Solutions Catalog at
http://catalog.lotus.com/wps/portal/workplace will not import into WebSphere
Studio Application Developer”
v “When importing WAR files into Rational Application Developer 6.0, nuisance
exceptions appear in OS console” on page 145
Login command customization fails
Solution: When creating your own implementation of one of the WebSphere Portal
classes, for example, Login or Logout modules, you must update IBM WebSphere
Application Server so that the classes load correctly.
1. Open the Administrative Console for WebSphere Application Server.
2. Click Environment, then Shared Libraries, then WPSlib.
3. Add your JAR file to Classpath.
4. Click OK.
5. Click Save to save the changes to the master configuration.
6. Restart the WebSphere_Portal application server.
Struts portlets from the IBM Workplace Solutions Catalog at
http://catalog.lotus.com/wps/portal/workplace will not import into
WebSphere Studio Application Developer
The new Struts Portlet Framework WAR files will not import into WebSphere
Studio Application Developer after downloading from the IBM Workplace
Solutions Catalog at http://catalog.lotus.com/wps/portal/workplace
(http://catalog.lotus.com/wps/portal/portalworkplace, NavCode: 1WP10003N).
This is because these WAR files contain 2 META-INF directories: one lower-case
and one upper-case. The existence of these two directories causes WebSphere
Studio to fail during the import.
144 Troubleshooting guide
Solution: This will be resolved with the next release of the Struts Portal
Framework. As a workaround, you can expand the WAR and then select ″Import″
as ″File System″ to import the individual files.
When importing WAR files into Rational Application Developer
6.0, nuisance exceptions appear in OS console
When using the WAR import wizard to import WAR files into Rational
Application Developer (RAD) 6.0, the following nuisance exceptions may appear in
OS console, but not in trace.log.
*** ERROR ***: Sat Apr 16 07:13:27 CST 2005
com.ibm.etools.j2ee.commonarchivecore.exception.ArchiveWrappedException
!Stack_trace_of_nested_exce!
com.ibm.etools.j2ee.commonarchivecore.exception.DeploymentDescriptorLoadException:
WEB-INF/web.xml
!Stack_trace_of_nested_exce!
com.ibm.etools.j2ee.commonarchivecore.exception.EmptyResourceException:
platform:/resource/<web_app_name>/WebContent/WEB-INF/web.xml
at com.ibm.etools.j2ee.commonarchivecore.util.ArchiveUtil.getRoot(Unknown Source)
...
Solution: This is a RAD 6.0 issue and fixed in RAD 6.0.0.1. Updates for RAD can
be located on the product homepage: http://www-128.ibm.com/developerworks/rational/products/rad/.
Troubleshooting portlets
This section contains information that can assist you in preventing, identifying, and
correcting problems related to IBM WebSphere Portal Enable for z/OS. For
information related to specific components, see the appropriate troubleshooting
topic.
v “Problem: Error sending/opening messages with large attachments in CPP Mail
and Calendar portlets” on page 146
v “Problem: Undo and redo not working correctly in rich text editor when
composing mail using Firefox browser” on page 146
v “Problem: European comma format for numbers not available in Retirement
Planner” on page 146
v “Problem: Configure proxy for MarketWatch portlets” on page 146
v “Problem: Export XML does not work when ″Popup Block″ is active (Netscape
only)” on page 147
v “Problem: Click-to-Action menu shown in English, not Chinese ” on page 147
v “Problem: The administration portlets do not officially support the browser
’Back’ or ’Refresh’ functions.” on page 147
v “Limitation: The properties portlet does not list all shareable pages.” on page
147
v “Limitation: Privileged user cannot set page properties or Personalization rules.”
on page 147
v “Problem: Buttons in Adminstration portlets may not function.” on page 148
v “Problem: Formatting and JavaScript problems occur in rendered Portal page”
on page 148
v “Problem: In Internet Explorer, using the Enter key to select a Browse button
causes a portlet error.” on page 148
v Problem: Some .war files are not deployed after upgrading WebSphere Portal
Chapter 1. Troubleshooting 145
Problem: Error sending/opening messages with large
attachments in CPP Mail and Calendar portlets
The size of messages (message body + attachments) that can be sent or opened by
the CPP Mail and Calendar portlets is limited by the amount of free heap space
available on the portal server JVM at the time that the operation is attempted. We
have successfully tested sending and opening messages of 50 MB in size on an
unloaded portal server with all supported back end mail servers, however, because
other factors such as server load affect the size of the free memory heap in the
JVM, this is not a guaranteed maximum message size which can be supported. We
recommend to use small attachments with a size wide below 50 MB to avoid heap
fragmentation and potential out of memory errors. Also the system should be
tuned - we recommend specifying the maximum JVM heapsize at 1216 MB on
Windows using the -Xmx option (For example, -Xmx1216M) in order to provide the
largest practical JVM heap and still leave enough system memory for the operating
system and other processes. See the WebSphere Portal 6.0.x Performance Tuning
Guide for more information on heap tuning for WebSphere Portal.
Problem: Undo and redo not working correctly in rich text editor
when composing mail using Firefox browser
When you are composing a mail message using the rich text editor in the Firefox
browser, clicking Undo (Ctrl+z) and Redo (Ctrl+y) may not perform as expected.
In some cases, when text should reappear, it does not. When text should disappear,
it does not.
This is a known limitation when using the Firefox browser.
Problem: European comma format for numbers not available in
Retirement Planner
Retirement Planner only allows users to use the format x.xx when entering
non-whole number values.
Problem: Configure proxy for MarketWatch portlets
The MarketWatch portlets My News, My Weather, and My Stocks assume that you
have direct access to the Internet to retrieve content for rendering in the portlets. If
access is only possible through a proxy, then the proxy must be configured in the
portlet by modifying its web.xml file.
Solution: There are four context level parameters in web.xml, and by default they
are all empty:
<context-param>
<param-name>proxyHost</param-name>
<param-value></param-value>
</context-param>
<context-param>
<param-name>proxyPort</param-name>
<param-value></param-value>
</context-param>
<context-param>
<param-name>proxyUserName</param-name>
<param-value></param-value>
</context-param>
146 Troubleshooting guide
<context-param>
<param-name>proxyPassword</param-name>
<param-value></param-value>
</context-param>
The values for these parameters should be:
1. proxyHost: The host name of proxy server (dns name or static IP address).
2. proxyPort: The proxy server port, such as 8080.
3. proxyUserName/proxyPassword: If the proxy server requires authentication,
specify the user ID and password for the proxyUserName and proxyPassword
parameters, respectively.
Problem: Export XML does not work when ″Popup Block″ is
active (Netscape only)
In Netscape/Mozilla, when ″Popup Block″ is active, if you try to use the ″Export
XML″ function within the Manage Pages portlet, nothing happens. An ″Export
successful″ message is displayed though no export has occurred. With
Popup-Blocker disabled, pages can be exported normally.
Solution: In order to disable ″Popup Block″ in Netscape/Mozilla, perform the
following steps:
1. Open Preferences window by going to Edit > Preferences.
2. Select Privacy & Security > Popup Windows.
3. Un-check Block unrequested popup windows.
4. Click OK.
Problem: Click-to-Action menu shown in English, not Chinese
After configuring the Click-to-Action menu of the JDBC portlet in English, when
you change the language of the browser to zh_CH, the menu still displays in
English.
Solution: Replace the Click-to-Action menu items with local language strings.
Problem: The administration portlets do not officially support the
browser ’Back’ or ’Refresh’ functions.
For a listing and description of the administration portlets, refer to Portal
administration portlets.
Limitation: The properties portlet does not list all shareable
pages.
The list of shareable pages displayed by the Properties portlet is limited to those
pages that the user can navigate to. As a result, a user might not be able to create
explicitly derived pages from some shareable pages.
Limitation: Privileged user cannot set page properties or
Personalization rules.
A user must have at least Editor privileges on a page to be able to edit the
properties on that page. Privileged users will not be able to edit a page’s properties
or edit personalization rules, because Personalization rules are part of a page’s
properties.
Chapter 1. Troubleshooting 147
Problem: Buttons in Adminstration portlets may not function.
Solution:Enable scripting in Microsoft Internet Explorer using the following steps:
1. Select the Tools menu.
2. Select Internet Options.
3. Select the Security tab.
4. Click the Custom level button.
5. Enable the entire Scripting section.
Problem: Formatting and JavaScript problems occur in rendered
Portal page
Formatting problems and JavaScript console errors and warnings occur when a
page is rendering. Formatting problems may include such things as excess white
space, alignment issues, and truncation. These problems may occur due to
inconsistencies in the way different browsers render markup as well as differences
due to the DocType specified for the page. This can be a particular problem when a
″strict″ DocType is specified but the markup is created based on an older
″transitional″ (″quirks″ mode) DocType.
Solution: Ensure that theme and portlet output are consistent with the DocType
specified by the theme the page uses. Either set the theme to use a different
DocType or update the rendered markup to be compatible with the selected
DocType.
Problem: In Internet Explorer, using the Enter key to select a
Browse button causes a portlet error.
In Internet Explorer, when you highlight a Browse button by tabbing and try
using the Enter key to bring up the browse window, the form is submitted instead.
This causes a portlet error. Instead of using the Enter key, select the Browse button
by tabbing and then use the space bar to bring up the file browser window.
Problem: The people picker for Document Manager does not
work after upgrading WebSphere Portal to version 6.0.1.1
Some .war files such as wps.war and lwp_peoplePickerServlet.war lose their web
module map to the web server after upgrading WebSphere Portal. This may cause
problems when searching on people; for example, the Document Manager People
Picker will fail.
Solution: Perform the following steps to redeploy the .war file:
1. Navigate to Applications → Enterprise Applications.
2. Click on the name: for example LWP People.
3. Click on Map modules to servers.
4. Select the appropriate module; for example People Picker Servlet
lwp_peoplePickerServlet.war.
5. From the Clusters and Servers drop-down menu, select the web
server.
6. Click OK and save the configuration, and regenerate webserver
plugin.
148 Troubleshooting guide
Troubleshooting Web Clipping portlet
The following section lists known problems and solutions related to Web clipping.
v “Problem: Error message says a certificate is missing when connecting to a
secure site”
v “Problem: SOCKS proxies are not supported for the Web Clipping Editor” on
page 150
v “Problem: No content appears in a portlet” on page 150
v “Problem: When using the Web Clipping Editor through Mozilla, users cannot
select HTML images” on page 150
v “Problem: Receive portlet unavailable error when browsing a portlet created
with the Web Clipping Editor” on page 151
v “Problem: Web Clipping does not work with Machine Translation” on page 151
v “Problem: Web Clipping does not support :” on page 151
v “Problem: Web Clipping does not show the selection clipped with HTML
clipping.” on page 151
v “Problem: Text is merged in the upper right corner of the screen” on page 151
Problem: Error message says a certificate is missing when
connecting to a secure site
If you attempt to connect to a secure site using the Web clipping portlet and get an
error message indicating that the needed certificate is missing, you will need to
add a certificate file to correct the problem.
Note: These instructions assume that a browser such as Internet Explorer can
successfully connect to the site and that it has the root certificate that is
needed.
Solution:
To add the necessary certificate, complete the following steps:
1. Open a browser, and enter the Web address of the secure site that you are
trying to connect to with the Web clipping portlet. After connecting to the site,
you should see the SSL Secured icon displayed in status bar of the browser.
2. Click File > Properties.
3. Click the Certificates button to display the Certificate dialog box.
4. Select the Certification Path tab.
5. Select the topmost root certificate entry in the tree. This is the name of the
certificate that you will need to export from the browser.
6. Click OK to close the dialog box.
7. Click Tools > Internet Options from the main menu of the browser.
8. Select the Content tab.
9. Click the Certificates button to display the Certificate dialog box.
10. Select the Trusted Root Certification Authorities tab.
11. Select the root that was previously identified.
12. Click the Export button to open the Certificate Export Wizard dialog.
13. Click Next in the wizard dialog box.
14. Select Base-64 encoded X.509 (.CER) as the format to use for the certificate
file.
Chapter 1. Troubleshooting 149
15. Click Next.
16. Type the file name that you want to use for the certificate file.
17. Click Browse, and select the directory to contain the .CER file.
18. Click Next.
19. Click Finish.
20. Copy the .CER file that you created, and place it into the
java\jre\lib\security directory, where WebSphere Application Server was
installed. For example, if WebSphere Application Server was installed in
C:\WebSphere\appserver, the .CER file must be saved in the
C:\WebSphere\appserver\java\jre\lib\security directory. Note: To verify
that you have located the correct directory, you should find the cacerts file in
the same directory.
21. Restart WebSphere Application Server, and attempt to connect to the secure
site with the Web Clipping portlet again.
Problem: SOCKS proxies are not supported for the Web Clipping
Editor
Under the Web Clipper Editor Advanced options, there is no option in the Modify
firewall options page to differentiate an HTTP proxy from a SOCKS proxy. This is
because only HTTP proxies are supported for the Web Clipping Editor.
Solution: When modifying the firewall options for a Web Clipping portlet, use
only HTTP proxies for your Proxy hostname and Proxy port.
Problem: No content appears in a portlet
When clicking on a link in a Web Clipping portlet, you might find that no content
appears.
Solution:
Ensure that:
1. The destination of the link is secured.
2. The URL in the link is valid.
3. The destination of the link is located in the internet and the proxy setting is
correct.
4. The URL in the link is not redirected.
If you work through those steps and content still does not appear, the problem
could be:
1. The destination of the link contains some functions of Javascript which are not
supported by the Web Clipper Editor in this release.
2. The destination of the link returns applets or embedded objects like Flash
which are not supported by the Web Clipper Editor in this release.
Problem: When using the Web Clipping Editor through Mozilla,
users cannot select HTML images
Mozilla is not supported for creating Web Clipping portlets.
Solution: Use either Microsoft Internet Explorer or Netscape Navigator as your
browser when creating Web Clipping portlets.
150 Troubleshooting guide
Problem: Receive portlet unavailable error when browsing a
portlet created with the Web Clipping Editor
If you have a Web clipped portlet that contains a link which requires a third party
authentication certificate, you might receive the following error when following
that link:
″This portlet is unavailable. If the problem persists, please contact the
portal administrator″
Solution: Apply the WebSphere Application Server fix that updates the JSSE code.
This fix can be found on the WebSphere Application Server Fix Pack and Fixes disc
for your operating system. The fix is as follows: /manualfixes/WAS_Security_07-07-2003_JSSE_cumulative_Fix.jar
Comments: If users will be clipping content from secure sites using https:// or
sites that have links to secure sites using https:// this fix should be applied.
Problem: Web Clipping does not work with Machine Translation
If you use a clipping that is in a locale other than the local locale of WebSphere
Portal, you get a wrong drop-down translation menu with
EnableViewerInitiatedTranslation according to the locale of WebSphere Portal,
but not according to the locale of the clipping portlet.
Solution: If you want to use machine translation to translate the clipping, you
must set the portlet parameter ContentLanguage with the locale of the clipping
portlet.
Problem: Web Clipping does not support “:”
The Web Clipping portlet does not support entering a single character “:” in the
URL to clip field.
Solution: Do not use “:” in the URL to clip field.
Problem: Web Clipping does not show the selection clipped with
HTML clipping.
Transcoding must be enabled in order for HTML clipping to work. See Creating a
Web clipping portlet for more information.
Problem: Text is merged in the upper right corner of the screen
The merged text is a limitation with the Web Clipping portlet due to the
position:absolute css attribute. The Web Clipping portlet does not modify any
CSS information in the clipped site, which causes the merged text.
Contact support
If you have determined that you need IBM assistance to solve a problem, complete
one of the following IBM support worksheets. The following worksheets include
the information that the IBM Support Center might need to help diagnose your
problem. Copy the worksheet into a text editor and fill in the blanks before
contacting IBM for support. If requested, you can then send the text file to IBM
through e-mail, or just print a copy for your own reference.
Chapter 1. Troubleshooting 151
For contact information, refer to the IBM Software Support site:
http://www.ibm.com/software/genservers/portal/support/
General installation troubleshooting worksheet
Description of the problem and the environment
1. Problem Summary:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
2. Fully qualified hostname and IP address of the target and source system(s):
________________________________________________________________________________
User IDs and passwords used:
________________________________________________________________________________
3. WebSphere Portal version, release, and PTF level (also please list any UMODs
applied):
________________________________________________________________________________
________________________________________________________________________________
4. WebSphere Application Server version, release, and PTF level (also please list
any UMODs:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
5. Web server product and version installed, if any (local or remote and on what
platform?):
________________________________________________________________________________
6. LDAP server product and version installed, if any (local or remote and on
what platform?):
________________________________________________________________________________
7. Database product and version installed, if any other than Cloudscape (local or
remote and on what platform?):
_____________________________________________________________________
8. If an external security manager is in use, please specify here (include
platform):
Tivoli Access Manager: ____________________________________________________________
Other: __________________________________________________________________________
9. WebSphere Portal’s operating system:
_______________________________________________
Operating System Patch/Maintenance/Service Pack Level: _______________________________
10. Number of CPUs on this server?
_____________________________________________________
Amount of RAM installed: __________________________________________________________
Amount of free hard disk space on all drives: __________________________________________
_______________________________________________________________________________
152 Troubleshooting guide
11. Steps to recreate:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
12. Describe the network environment:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
Refer to these files, capture them for later review:
v Any log or trace files relevant to the investigation
v Any configuration files of the server or its components
v RASUtils.jar output (WPRASCollect.zip)
v Screen shots
General configuration troubleshooting worksheet
Description of the problem and the environment
1. Problem Summary:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
2. Fully qualified hostname and IP address of the target and source system(s):
________________________________________________________________________________
User IDs and passwords used:
________________________________________________________________________________
3. WebSphere Portal version, release, and PTF level (also please list any UMODs
applied):
________________________________________________________________________________
________________________________________________________________________________
4. WebSphere Application Server version, release, and PTF level (also please list
UMODs applied):
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
5. Web server product and version installed, if any (local or remote and on what
platform?):
________________________________________________________________________________
6. LDAP server product and version installed, if any (local or remote and on
what platform?):
Chapter 1. Troubleshooting 153
________________________________________________________________________________
7. Database product and version installed, if any other than Cloudscape (local or
remote and on what platform?):
________________________________________________________________________________
8. If an external security manager is in use, please specify here (include
platform):
Tivoli Access Manager:
____________________________________________________________
Other:
__________________________________________________________________________
9. WebSphere Portal’s operating system:
_______________________________________________
Operating System Patch/Maintenance/Service Pack Level:
_______________________________
10. Number of CPUs on this server?
_____________________________________________________
Amount of RAM installed:
__________________________________________________________
Amount of free hard disk space on all drives:
__________________________________________
_______________________________________________________________________________
11. Steps to recreate:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
12. Describe the network environment:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
_____________________________________________________________________________________________________________________________________
Refer to these files, capture them for later review:
v Any log or trace files relevant to the investigation
v Any configuration files of the server or its components
v RASUtils.jar output (WPRASCollect.zip)
v Screen shots
General customization troubleshooting worksheet
Description of the problem and the environment
1. Problem Summary:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
154 Troubleshooting guide
________________________________________________________________________________
________________________________________________________________________________
2. Fully qualified hostname and IP address of the target and source system(s):
________________________________________________________________________________
User IDs and passwords used:
________________________________________________________________________________
3. WebSphere Portal version, release, and PTF level (also please list any PTFs
applied):
________________________________________________________________________________
________________________________________________________________________________
4. WebSphere Application Server version, release, and PTF level (also please list
any UMODs applied)
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
5. Web server product and version installed, if any (local or remote and on what
platform?):
________________________________________________________________________________
6. LDAP server product and version installed, if any (local or remote and on
what platform?):
________________________________________________________________________________
7. Database product and version installed, if any other than Cloudscape (local or
remote and on what platform?):
___________________________________________________________________
8. If an external security manager is in use, please specify here (include
platform):
Tivoli Access Manager: ____________________________________________________________
Other: __________________________________________________________________________
9. WebSphere Portal’s operating system:
_______________________________________________
Operating System Patch/Maintenance/Service Pack Level: _______________________________
10. Number of CPUs on this server?
_____________________________________________________
Amount of RAM installed: __________________________________________________________
Amount of free hard disk space on all drives: __________________________________________
_______________________________________________________________________________
11. Steps to recreate:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
Chapter 1. Troubleshooting 155
________________________________________________________________________________
________________________________________________________________________________
12. Describe the network environment:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
Refer to these files, capture them for later review:
v Any log or trace files relevant to the investigation
v Any configuration files of the server or its components
v Sample code archived for IBM support
v Screen shots
General runtime troubleshooting worksheet
Description of the problem and the environment
1. Problem Summary:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
2. Fully qualified hostname and IP address of the involved system(s):
________________________________________________________________________________
User IDs and passwords used:
________________________________________________________________________________
3. WebSphere Portal version, release, and PTF level (also please list any UMODs
applied):
________________________________________________________________________________
________________________________________________________________________________
4. WebSphere Application Server version, release, and PTF level (also please list
any UMODs applied):
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
5. Web server product and version installed, if any (local or remote and on what
platform?):
________________________________________________________________________________
6. LDAP server product and version installed, if any (local or remote and on
what platform?):
________________________________________________________________________________
156 Troubleshooting guide
7. Database product and version installed, if any other than Cloudscape (local or
remote and on what platform?):
________________________________________________________________________________
8. If an external security manager is in use, please specify here (include
platform):
Tivoli Access Manager: ____________________________________________________________
Other: __________________________________________________________________________
9. WebSphere Portal’s operating system:
_______________________________________________
Operating System Patch/Maintenance/Service Pack Level: _______________________________
10. Number of CPUs on this server?
_____________________________________________________
Amount of RAM installed: __________________________________________________________
Amount of free hard disk space on all drives: __________________________________________
_______________________________________________________________________________
11. Steps to recreate:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
12. Describe the network environment:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
Refer to these files, capture them for later review:
v Any log or trace files relevant to the investigation
v Any configuration files of the server or its components
v Screen shots
General programming troubleshooting worksheet
Description of the problem and the environment
1. Problem Summary:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
Chapter 1. Troubleshooting 157
2. User IDs and access privileges involved (for example, ’wpsadmin/Administrator’):
________________________________________________________________________________
3. WebSphere Portal version, release, and PTF level (also please list any UMODs
applied):
________________________________________________________________________________
________________________________________________________________________________
4. WebSphere Application Server version, release, and PTF level (also please list
any UMODs applied):
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
5. Development (IDE) product and version installed, and on what platform?:
________________________________________________________________________________
6. Java 2 SDK product and version installed, (java-full version output):
________________________________________________________________________________
7. Web server product and version installed, if any (local or remote and on what
platform?):
________________________________________________________________________________
8. LDAP server product and version installed, if any (local or remote and on
what platform?):
________________________________________________________________________________
9. Database product and version installed, if any other than Cloudscape (local or
remote and on what platform?):
____________________________________________________________________
10. If an external security manager is in use, please specify here (include
platform):
Tivoli Access Manager: ____________________________________________________________
Other: __________________________________________________________________________
11. WebSphere Portal’s operating system:
________________________________________________
Operating System Patch/Maintenance/Service Pack Level: _______________________________
12. Number of CPUs on this server?
_____________________________________________________
Amount of RAM installed: __________________________________________________________
Amount of free hard disk space on all drives: __________________________________________
_______________________________________________________________________________
13. Please have answers to these questions ready: What methods are in use?
________________________________________________________________________________
________________________________________________________________________________
Are there any dependent JAR files? ___________________________________________________
158 Troubleshooting guide
What is the overall goal of the portlet? ________________________________________________
________________________________________________________________________________
Does it work in the Portal Toolkit’s Test Environment or in a stand-alone Portal? ______________
Does the portlet use the Struts portal framework or WSRP? _________________________
_________________________________________________________________________________
Does the portlet use the standard portlet API or the IBM portlet API _________________________
_________________________________________________________________________________
14. Steps to recreate:
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
Refer to these files, capture them for later review:
v Sample code or testcase archived for sharing with IBM support
v Any log or trace files relevant to the investigation
v Any configuration files of the server or its components
v Screen shots
Message catalog
The Message catalog lists many of the informational, warning, and error messages
for this product.
Reading messages
Each message code consists of a component identifier, a unique number, and a
message identifier. Here are some examples.
EJPXX1234E
Where:
v EJPXX is the component identifier, where XX represents a component.
v 1234 is the unique four-digit number.
v E is for Error.
EJPIC1001I
Where:
v EJPIC is the component identifier for the installation wrapper.
v 1001 is the unique four-digit number.
v I is for Information.
EJPAA1008W
Chapter 1. Troubleshooting 159
Where:
v EJPAA is the component identifier for administration portlets.
v 1008 is the unique four-digit number.
v W is for Warning.
160 Troubleshooting guide
Chapter 2. Additional resources
Additional information that can help you install, configure, or administer the
products provided with IBM WebSphere Portal Enable for z/OS is available. You
can locate information on the WebSphere Portal Web site and other IBM Web sites,
and you can read the product documentation that is provided on the WebSphere
Portal CDs.
Resources for learning
The following section contains links to supplemental information.
This information resides on IBM and non-IBM Internet sites, whose sponsors
control the technical accuracy of the information. These links are provided for
convenience. Some information is useful, all or in part, for understanding the IBM
WebSphere Portal Enable for z/OS product but might not be specific to the
WebSphere Portal product itself. When possible, links are provided to technical
papers and IBM Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.
The following links take you to relevant IBM support and publications sites:
Additional resources
This topic includes links to general resources that might contain relevant
supplemental information.
The information resides on IBM and non-IBM Internet sites, whose sponsors
control the technical accuracy of the information. These links are provided for
convenience. Some information is useful, all or in part, for understanding the IBM
WebSphere Portal Enable for z/OS product but might not be specific to the
WebSphere Portal product itself. When possible, links are provided to technical
papers and IBM Redbooks that supplement the broad coverage of the release
documentation with in-depth examinations of particular product areas.
The following links take you to relevant IBM support and publications sites:
IBM WebSphere Portal Version 6.0 - What’s new?
What’s new in WebSphere Portal Version 6?
This article describes the highlights in IBM WebSphere Portal Version 6.0,
and is a good starting point for understanding the new version content
and the improvements since previous versions.
developerWorks WebSphere
WebSphere Portal zone
The home of technical information for developers and administrators
working with WebSphere products. You can do the following:
v Download WebSphere software
v Take a fast path to developer domain zones, such as WebSphere Portal,
IBM WebSphere Application Server, and WebSphere development tools
v Learn about WebSphere products through a newcomers page, tutorials,
technology previews, training, and IBM Redbooks
© Copyright IBM Corp. 2000, 2006 161
v Get answers to questions about WebSphere products
v Join the WebSphere community, where you can keep up with the latest
developments and technical papers
IBM Redbooks
http://www.redbooks.ibm.com/
Publications developed and published by IBM’s International Technical
Support Organization (the ITSO). The IBM Redbooks site contains
references for all IBM products. Search the Redbooks for documents
specific to WebSphere Application Server.
Additional resources for planning
This topic includes links to additional resources about planning.
Use the following links to find relevant supplemental information. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical
accuracy of the information.
These links are provided for convenience. Sometimes, the information is not
specific to the IBM WebSphere Portal Enable for z/OS product, but is useful all or
in part for understanding the product. When possible, links are provided to
technical papers and IBM Redbooks that supplement the broad coverage of the
release documentation with in-depth examinations of particular product areas.
Most of these link were written for previous versions of WebSphere Portal, but still
contain some relevant information. Search for updated content on the main site of
each link if you need more information.
Guide to WebSphere Portal
http://www3.software.ibm.com/ibmdl/pub/software/dw/wes/pdf/portal5whitepaper.pdf
This document provides an overview of the WebSphere Portal product
technology, including its business and technical benefits. It is intended to
help customers, independent software vendors, and application architects
understand and plan their use of WebSphere Portal. Concepts such as
portlets, portal applications, content, security, user management,
administration, collaboration, and more are described, including highlights
of related products that can be used with WebSphere Portal.
IBM WebSphere software platform home page
http://www.ibm.com/software/websphere/
The IBM WebSphere software platform home page introduces WebSphere
products and describes how companies can easily transform to an
e-business, with software that can grow as fast as the business it supports.
developerWorks: IBM Patterns for e-business
http://www.ibm.com/developerworks/patterns/index.html
The IBM developerWorks site is the source for IBM patterns for e-business,
a set of tested, reusable intellectual assets that you can use to design and
implement your e-business network and architecture.
A Secure Portal using WebSphere Portal V5 and Tivoli Access Manager,
SG24-6077-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/
162 Troubleshooting guide
9445fa5b416f6e32852569ae006bb65f/3d96ba9fea9a252985256d6e0064f0f7?OpenDocument
The focus of this publication is the security aspect of the WebSphere Portal
single access point with centralized authentication and authorization. Other
aspects of security like auditing, firewall, and DMZ are not in the scope of
this document.
Deploying Lotus QuickPlace, SG24-6535-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246535.html
This IBM Redbook shows you how to install, configure, and deploy Lotus
QuickPlace in your organization. It gives step-by-step installation
instructions for the Lotus QuickPlace server and describes how to
configure it to use the current directories of your organization.
IBM WebSphere Application Server V6.0 System Management and
Configuration WebSphere Handbook Series, SG24-6451-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246195.html
This IBM Redbook provides the knowledge needed to implement a
WebSphere Application Server V5.1 Network Deployment runtime
environment, to package and deploy Web applications, and to perform
ongoing management of the WebSphere environment. It is one in a series
of handbooks designed to give you in-depth information on the entire
range of WebSphere Application Server products.
WebSphere Application Server V6 Security Handbook (SG24-6316-00)
http://www.redbooks.ibm.com/abstracts/sg246316.html?Open
This IBM Redbook describes how to design, develop, and deploy secure
e-business applications using WebSphere Studio Application Developer
Version 5. It includes a detailed overview of WebSphere Application Server
V5 Security, including J2EE security, modules and components of a J2EE
enterprise application, and programmatic security techniques. It also
describes end-to-end security solutions where WebSphere Studio
Application Developer V5 is part of an enterprise solution, including
integration between WebSphere Studio Application Developer V5 and
Tivoli Access Manager .
Working with the Lotus Sametime Client Toolkits, SG24-6666-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/f2b73cdd644ac8a485256acc005ca7c7?OpenDocument
This IBM Redbook is for developers and architects who want to use Lotus
Sametime functionality in applications based on Java, C++, COM, or
HTML and JavaScript. It explores capabilities offered by the different Lotus
Sametime client toolkits, which you can use to add functionality to existing
applications and to create powerful new applications that enable real-time
collaboration. It discusses event-based programming, Lotus Sametime
services, and the Lotus Sametime Place architecture.
WebSphere Portal Server and DB2 Information Integrator: A Synergistic
Solution, SG24-6433-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246433.html
Chapter 2. Additional resources 163
This IBM Redbook provides examples of the synergy between WebSphere
Portal Server and DB2 Information Integrator in delivering portal solutions,
and will include sample portlets exploiting SQL, UDFs, JDBC, and Web
Services.
Lotus Domino 6.5.1 and Extended Products Integration Guide
http://www.redbooks.ibm.com/abstracts/sg246357.html
This IBM Redbook discusses how to install, configure, and integrate
Release 6.5.1 of IBM Lotus Domino and the Extended Products.
DB2 for z/OS and OS/390: Ready for Java, SG-2464-35
http://www.redbooks.ibm.com/abstracts/sg246435.html?Open
This IBM Redbook shows how Java and DB2 for z/OS and OS/390 can
work together and form a strong combination that can run your
mission-critical enterprise applications. This publication focusses on the
new IBM Universal Driver for SQLJ and JDBC, IBM’s new JDBC driver
implementation, supporting both Type 2 and Type 4 driver connectivity to
the members of the DB2 family, including DB2 for z/OS, and DB2 for
Linux, Unix and Windows.
WebSphere for z/OS V5 Connectivity Handbook, SG-2470-64
http://www.redbooks.ibm.com/abstracts/sg247064.html?Open
This IBM Redbook helps you install, tailor, and configure adapters and the
Java 2 Platform, Enterprise Edition (J2EE) Connector Architecture
(J2CA)-compliant and other connectors that are used by WebSphere
Application Server for z/OS Version 5.
WebSphere for z/OS V4 Problem Determination, SG-2468-80
http://www.redbooks.ibm.com/abstracts/sg246880.html?Open
This IBM Redbook will help customers and IBMers to understand the
different aspects of problem determination for WebSphere for z/OS Version
4.
Enabling JCE & JSSE Security in WebSphere for zOS Version 5, TD101074
http://www-1.ibm.com/support/docview.wss?uid=tss1td101074
WebSphere for z/OS Version 5 provides support for JCE (Java
Cryptography Extensions) and JSSE (Java Secure Socket Extensions). This
document covers updating the java.security file to specify additional
providers.
Performance and tuning tips for WebSphere Application Server for z/OS
Version 5.0, TD7005039
http://www-1.ibm.com/support/docview.wss?uid=swg27005039
This document contains performance and tuning tips for z/OS, tuning for
subsystems that run on WebSphere Application Server, including DB2,
CICS, RACF, TCP/IP, and MQSeries/Java Messaging Services (JMS), as
well as tuning tips for WebSphere Application Server runtime environment.
Performance Engineering & Tuning WebSphere for z/OS Version 5, PRS804
http://www-1.ibm.com/support/docview.wss?uid=tss1prs804
This document presents information about how to determine if your z/OS
system has been tuned for optimal WebSphere performance. Tuning
recommendations for WebSphere Application Server for z/OS Version 5.0.1,
164 Troubleshooting guide
including configuration considerations, z/OS system tuning, WebSphere
and application tuning, and the effective use of tools.
Using DB2 for zOS in WebSphere for zOS Version 5, TD101072
http://www-1.ibm.com/support/docview.wss?uid=tss1td101072
Setting up a JDBC provider for DB2 for z/OS and creation of a DataSource
in WebSphere for z/OS involves the JDBC driver locating and loading the
DSNJDBC_JDBCProfile.ser file. DB2 for z/OS Version 7 has enhanced the
mechanism by which the JDBC driver locates and loads this file to
accommodate WebSphere for z/OS Version 5, as of APAR PQ69861. This
document covers installing a JDBC provider using this new support.
Additional resources for installation
This topic includes links to additional resources about installation.
Use the following links to find relevant supplemental information. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical
accuracy of the information.
These links are provided for convenience. Sometimes, the information is not
specific to the IBM WebSphere Portal Enable for z/OS product, but is useful all or
in part for understanding the product. When possible, links are provided to
technical papers and IBM Redbooks that supplement the broad coverage of the
release documentation with in-depth examinations of particular product areas.
IBM WebSphere Portal for Multiplatforms V5 Handbook, SG24-6098-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246098.html
The IBM WebSphere Portal for Multiplatforms V5 Handbook will help you
to understand the WebSphere Portal architecture, how to install, tailor and
configure WebSphere Portal, and how to administer and customize portal
pages using WebSphere Portal.
WebSphere Portal zone Web site
http://www.ibm.com/developerworks/websphere/zones/portal/
Technical information for developers and administrators of WebSphere
Portal.
IBM Redbooks Web site
http://www.redbooks.ibm.com/
Publications developed and published by IBM’s International Technical
Support Organization (the ITSO). The IBM Redbooks site contains
references for all IBM products. Search the Redbooks for documents
specific to WebSphere Portal.
Additional resources for administration
This topic includes links to additional resources about administration.
Use the following links to find relevant supplemental information. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical
accuracy of the information.
These links are provided for convenience. Sometimes, the information is not
specific to the IBM WebSphere Portal Enable for z/OS product, but is useful all or
Chapter 2. Additional resources 165
in part for understanding the product. When possible, links are provided to
technical papers and IBM Redbooks that supplement the broad coverage of the
release documentation with in-depth examinations of particular product areas.
Develop high performance Web sites with both static and dynamic content
using WebSphere Portal V5.1
http://www.ibm.com/developerworks/websphere/techjournal/0506_liesche/0506_liesche.html
This paper explains how and why to run an entire Web site -- including
the static parts -- on WebSphere Portal with unified deployment,
administration, and content management
A Secure Portal Using WebSphere Portal V5 and Tivoli Access Manager
V4.1, SG24-6077-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg246077.html
Portals provide a personalized single point of access to applications,
content, people and processes through a Web interface. They also provide
underlying services for these applications, such as security, search,
collaboration and workflow.
A Secure Portal Extended With Single Sign-On, REDP-3743-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/redp3743.html
Many portals are required to access external applications that need some
form of user authentication. In most cases, the user credentials required by
these applications will differ from those used by WebSphere Portal. While
it is possible for the portlet to prompt the user for this credential
information and then present it to the external application, such an
approach is seldom implemented due to the unsatisfactory user experience.
Therefore, a single sign-on (SSO) is required to provide seamless access to
the different applications in a portal solution.
Develop and Deploy a Secure Portal Solution, Using WebSphere Portal
V5.0.2 and Tivoli Access Manager V5.1, SG24-6325-00
http://publib-b.boulder.ibm.com/Redbooks.nsf/RedpieceAbstracts/sg246325.html
Portals provide a personalized single point of access to applications,
content, and processes through a Web interface. Secure portal solutions are
needed to address the common security challenges, such as authentication,
authorization and single sign-on.
The IBM Terminology Web site
http://www.ibm.com/software/globalization/terminology/
This Web site defines technical terms that are used in many IBM products,
and consolidates the terminology into one convenient location. This
resource is provided for information purposes only and is updated
periodically. IBM takes no responsibility for the accuracy of the information
it contains.
Additional resources for development
This topic includes links to additional resources about development.
166 Troubleshooting guide
Use the following links to find relevant supplemental information. The information
resides on IBM and non-IBM Internet sites, whose sponsors control the technical
accuracy of the information.
These links are provided for convenience. Sometimes, the information is not
specific to the IBM WebSphere Portal Enable for z/OS product, but is useful all or
in part for understanding the product. When possible, links are provided to
technical papers and IBM Redbooks that supplement the broad coverage of the
release documentation with in-depth examinations of particular product areas.
View links to additional information about:
v “Programming instructions and examples”
v “Programming specifications” on page 168
v “Additional applications” on page 168
Programming instructions and examples
IBM WebSphere Portal V5 A Guide for Portlet Application Development,
SG24-6076-00
http://www.redbooks.ibm.com/redbooks/pdfs/sg246076.pdf
This IBM Redbook helps you design, develop and implement portlet
applications using the IBM WebSphere Studio Site Developer and the
Portal Toolkit V5. The information provided in this Redbook targets
Business-to-Employee (B2E) enterprise applications, but most of the
scenarios presented apply to Business-to-Consumer (B2C) applications as
well. In this Redbook, you will find step-by-step examples and scenarios
showing ways to integrate your enterprise applications into an IBM
WebSphere Portal environment using the WebSphere Portal APIs provided
by the Portal Toolkit to develop portlets as well as extend your portlet
capabilities to use other advanced functions such as cooperative portlets,
national language support, action events, portlet messaging, Credential
Vault, Web Services and portlet debugging capabilities.
IBM developerWorks
http://www.ibm.com/developerworks/
IBM developerWorks contains many excellent resources for developers,
including tutorials on Web development-related topics. There is an
excellent tutorial on the JDBC API.
Articles: Servlets
http://java.sun.com/developer/technicalArticles/Servlets/index.html
Articles about writing servlets.
Articles: JavaServer Pages
http://java.sun.com/products/jsp/reference/techart/index.html
Articles about writing JSPs.
Articles: JavaServer Faces
http://java.sun.com/j2ee/javaserverfaces/index.jsp
Articles about writing JSPs.
Chapter 2. Additional resources 167
Programming specifications
Java Authentication and Authorization Service (JAAS)
http://java.sun.com/products/jaas/index-10.html
For more information about JAAS specifications, visit the Sun site that is
previously mentioned.
Portlet specification
http://jcp.org/jsr/detail/168.jsp
For more information about portlet specifications, visit the Sun sponsored
site that is previously mentioned.
J2EE information
http://java.sun.com/j2ee/
For more information about J2EE specifications, visit the Sun site that is
previously mentioned.
Additional applications
IBM Workplace Solutions Catalog at http://catalog.lotus.com/wps/portal/workplace
The portlets that are described in this IBM Workplace Solutions Catalog at
http://catalog.lotus.com/wps/portal/workplace are provided by many
parties, including IBM. The portlets are listed by IBM in this catalog for
your information purposes only. Each of the portlets has an applicable user
license agreement. The terms and conditions under which a specific portlet
can be used and the responsibilities of the user and the portlet provider are
described in the user license agreement for that portlet.
Directory structure
This topic shows the naming conventions used to denote the location of files on
the servers and the types of resources you can find in those directories.
v “WebSphere Portal directory structure (portal_server_root)”
v “WebSphere Application Server directory structure (app_server_root)” on page
170
v “Lotus Domino directory structure (domino_server_root and domino_data_root)”
on page 172
v “Directories for languages” on page 172
WebSphere Portal directory structure (portal_server_root)
Throughout this documentation, the install location for the portal server
component of WebSphere Portal is noted as portal_server_root, which is the
config root.
The following table shows the default location if it is not otherwise specified
during installation:
Operating system Location
z/OS /usr/lpp/zPortalServer/V6R0 (install root)
/PortalServer/V6R0/Portal (config root)
168 Troubleshooting guide
WebSphere Portal directory structure after installation on z/OS
WebSphere Portal has the following directory structure after installation. All
directories are r/w on the config root. The content, however, might be r/w (files
are copied) or r/o (files are symlinked).
z/OS
portal_server_root Root directory for WebSphere Portal.
| |
| + collections (mixed) Directory for collections.
| |
| + designer (mixed) Directory for designer runtime.
| |
| + license (mixed) Directory for license files.
| |
| + sync (mixed) Directory for the sync server.
| |
| + was (mixed) Directory for files to be linked into the
| | WebSphere Application Server directory.
| |
| + workflow (mixed) Directory for the workflow applications
|
+-- bin (mixed) WebSphere Portal tools (scripts must be r/w; all
| other files r/o).
|
+-- cloudscape (r/w) Cloudscape database files.
|
+-- config Portal configuration files.
|
+-- deployed (r/w) Copies of the .EAR and .WAR files for
| | installed portlet applications.
| |
| + archive This directory contains all deployed .WAR files,
| except for predeployed ones.
|
+-- doc (r/o) WebSphere Portal information center and Javadoc.
|
+-- IBMTrans (r/w) Transcoding component
| (these subdirectories are linked r/o: bin,
| lib, plugins, toolkit, XMLConfigRules,
| and xmlconfig_stage).
|
+-- installableApps (r/w) WAR files prior to deployment.
|
+-- installableConnectors
|
+-- installedApps (r/w) Active portlet applications extracted
| to the WAR file directory structure
| (created during installation).
|
+-- itlm IBM Tivoli License Manager files.
|
+-- jcr Java Content Repository files.
|
+-- log (r/w) WebSphere Portal log files
| (created during installation).
|
+-- migration (r/w) Scripts used to assist in migrating from
| previous releases of WebSphere Portal.
|
+-- odc (mixed) On-demand client files (./com is r/w; all other
| subdirectories are r/o).
|
+-- pzn (r/w) Personalization runtime and
| resources (This component copies files during
Chapter 2. Additional resources 169
| installation to a WebSphere subdirectory).
|
+-- shared
| |
| +-- ext (r/o) Contains various .JAR files.
| |
| +-- app (r/w) WebSphere Portal runtime JARs, TLDs, and other
| | resources.
| |
| +-- config r/w) Portal configuration files.
| | |
| | +- services Personalization, Feedback and LikeMinds configuration files.
| |
| +-- nls (r/o) WebSphere Portal NLS files.
|
+-- service Contains fix packages.
|
+-- version (r/w) Version information for various components.
|
+-- wcm Source Web application files for Web Content Management
|
+-- wmm (mixed) Member Manager configuration,
| including attributes of portal users (code will be r/o).
WebSphere Application Server directory structure
(app_server_root)
WebSphere Application Server installation directory
Throughout this documentation, the install location for WebSphere
Application Server is noted as app_server_root.
The following table shows the default WebSphere Application Server
installation location if it is not otherwise specified during installation:
Default location of WebSphere Application Server
Operating system Location
z/OS /WebSphere/V6R0/AppServer
WebSphere Application Server profile directory
Throughout this documentation, the location for the WebSphere
Application Server profiles is noted as was_profile_root.
The following table shows the default WebSphere Application Server
location for profiles.
Default location of WebSphere Application Server profiles
Operating system Location
z/OS app_server_root/profiles/default
WebSphere Application Server configuration directory
Throughout this documentation, the location for the WebSphere
Application Server configuration files is noted as was_config_root.
The following table shows the default WebSphere Application Server
location.
170 Troubleshooting guide
Default location of WebSphere Application Server configuration files
Operating system Location
z/OS was_profile_root/config
wps.war directory
The WebSphere Portal enterprise application is installed to the following
location within WebSphere Application Server’s path:
was_profile_root/installedApps/cell_name/wps.ear/wps.war
The WAR file directory structure for the WebSphere Portal enterprise
application contains the following resources.
wps.war
|
+-- c2a Cooperative portlet resources
|
+-- doc Portal-level help and readme
|
+-- DocEditor JSPs for the Rich Text Editor
|
+-- dtd XML DTDs and schema definitions
|
+-- html License and privacy HTML files for the portal.
|
+-- images Common images for the portal
|
+-- menu Resources for MenuService applet
| (Collaborative Components API)
|
+-- META-INF Standard Java MANIFEST.MF for the
| portal Web application
|
+-- peopleawareness Resources for the people awareness features
|
+-- screens Screen JSPs for the portal
| |
| +-- markup_name Subdirectory for each markup type
|
|-- skins Skin JSPs for the portal
| |
| +-- markup_name Subdirectory for each markup type
|
|-- themes Theme JSPs for the portal
| |
| +-- markup_name Subdirectory for each markup type
|
+-- virtualportal XMLAccess file for setting up a virtual portal
|
+-- WEB-INF Protected resources for the portal Web application
|
+-- wts JavaScript resources for Transcoding Technology
The following directories contain resources for customization. Resources for
all other directories in the portal Web application directory structure must
not be modified.
v /doc
v /html
v /images
v /screens
v /skins
Chapter 2. Additional resources 171
v /themes
v /virtualportal
Lotus Domino directory structure (domino_server_root and
domino_data_root)
Throughout this documentation, the install location for the Lotus Domino server
software is noted as domino_server_root, which is the install root.
The following table shows the default location if it is not otherwise specified
during installation:
Operating system Location
z/OS /usr/lpp/lotus (install root)
The Lotus Domino server data directory is noted as domino_data_root, which is the
config root.
The following table shows the default location of the Domino data directory if it is
not otherwise specified during installation:
Operating system Location
z/OS /usr/lpp/lotus/data (config root)
Directories for languages
The following shows the languages supported by WebSphere Portal and the
directories used for storing locale-specific resources. These directories are used in
portlet Web application directories and in the WebSphere Portal enterprise
application (themes, skins, and other Web application resources).
Language
(locale) Directory
Language
(locale) Directory
Language
(locale) Directory
Arabic /ar Hungarian /hu Romanian /ro
Catalan /ca Italian /it Russian /ru
Czech /cs Hebrew /iw Slovak /sk
Danish /da Japanese /ja Slovenian /sl
German /de Korean /ko Swedish /sv
English /en Dutch /nl Thai /th
Greek /el Norwegian /no Turkish /tr
Spanish /es Polish /pl Ukrainian /uk
Finnish /fi Portuguese /pt Simplified
Chinese
/zh
French /fr Brazilian
Portuguese
/pt_BR Traditional
Chinese
/zh_TW
172 Troubleshooting guide
Chapter 3. Directory structure
This topic shows the naming conventions used to denote the location of files on
the servers and the types of resources you can find in those directories.
v “WebSphere Portal directory structure (portal_server_root)” on page 168
v “WebSphere Application Server directory structure (app_server_root)” on page
170
v “Lotus Domino directory structure (domino_server_root and domino_data_root)”
on page 172
v “Directories for languages” on page 172
WebSphere Portal directory structure (portal_server_root)
Throughout this documentation, the install location for the portal server
component of WebSphere Portal is noted as portal_server_root, which is the
config root.
The following table shows the default location if it is not otherwise specified
during installation:
Operating system Location
z/OS /usr/lpp/zPortalServer/V6R0 (install root)
/PortalServer/V6R0/Portal (config root)
WebSphere Portal directory structure after installation on z/OS
WebSphere Portal has the following directory structure after installation. All
directories are r/w on the config root. The content, however, might be r/w (files
are copied) or r/o (files are symlinked).
z/OS
portal_server_root Root directory for WebSphere Portal.
| |
| + collections (mixed) Directory for collections.
| |
| + designer (mixed) Directory for designer runtime.
| |
| + license (mixed) Directory for license files.
| |
| + sync (mixed) Directory for the sync server.
| |
| + was (mixed) Directory for files to be linked into the
| | WebSphere Application Server directory.
| |
| + workflow (mixed) Directory for the workflow applications
|
+-- bin (mixed) WebSphere Portal tools (scripts must be r/w; all
| other files r/o).
|
+-- cloudscape (r/w) Cloudscape database files.
|
+-- config Portal configuration files.
|
+-- deployed (r/w) Copies of the .EAR and .WAR files for
| | installed portlet applications.
© Copyright IBM Corp. 2000, 2006 173
| |
| + archive This directory contains all deployed .WAR files,
| except for predeployed ones.
|
+-- doc (r/o) WebSphere Portal information center and Javadoc.
|
+-- IBMTrans (r/w) Transcoding component
| (these subdirectories are linked r/o: bin,
| lib, plugins, toolkit, XMLConfigRules,
| and xmlconfig_stage).
|
+-- installableApps (r/w) WAR files prior to deployment.
|
+-- installableConnectors
|
+-- installedApps (r/w) Active portlet applications extracted
| to the WAR file directory structure
| (created during installation).
|
+-- itlm IBM Tivoli License Manager files.
|
+-- jcr Java Content Repository files.
|
+-- log (r/w) WebSphere Portal log files
| (created during installation).
|
+-- migration (r/w) Scripts used to assist in migrating from
| previous releases of WebSphere Portal.
|
+-- odc (mixed) On-demand client files (./com is r/w; all other
| subdirectories are r/o).
|
+-- pzn (r/w) Personalization runtime and
| resources (This component copies files during
| installation to a WebSphere subdirectory).
|
+-- shared
| |
| +-- ext (r/o) Contains various .JAR files.
| |
| +-- app (r/w) WebSphere Portal runtime JARs, TLDs, and other
| | resources.
| |
| +-- config r/w) Portal configuration files.
| | |
| | +- services Personalization, Feedback and LikeMinds configuration files.
| |
| +-- nls (r/o) WebSphere Portal NLS files.
|
+-- service Contains fix packages.
|
+-- version (r/w) Version information for various components.
|
+-- wcm Source Web application files for Web Content Management
|
+-- wmm (mixed) Member Manager configuration,
| including attributes of portal users (code will be r/o).
WebSphere Application Server directory structure
(app_server_root)
WebSphere Application Server installation directory
Throughout this documentation, the install location for WebSphere
Application Server is noted as app_server_root.
174 Troubleshooting guide
The following table shows the default WebSphere Application Server
installation location if it is not otherwise specified during installation:
Default location of WebSphere Application Server
Operating system Location
z/OS /WebSphere/V6R0/AppServer
WebSphere Application Server profile directory
Throughout this documentation, the location for the WebSphere
Application Server profiles is noted as was_profile_root.
The following table shows the default WebSphere Application Server
location for profiles.
Default location of WebSphere Application Server profiles
Operating system Location
z/OS app_server_root/profiles/default
WebSphere Application Server configuration directory
Throughout this documentation, the location for the WebSphere
Application Server configuration files is noted as was_config_root.
The following table shows the default WebSphere Application Server
location.
Default location of WebSphere Application Server configuration files
Operating system Location
z/OS was_profile_root/config
wps.war directory
The WebSphere Portal enterprise application is installed to the following
location within WebSphere Application Server’s path:
was_profile_root/installedApps/cell_name/wps.ear/wps.war
The WAR file directory structure for the WebSphere Portal enterprise
application contains the following resources.
wps.war
|
+-- c2a Cooperative portlet resources
|
+-- doc Portal-level help and readme
|
+-- DocEditor JSPs for the Rich Text Editor
|
+-- dtd XML DTDs and schema definitions
|
+-- html License and privacy HTML files for the portal.
|
+-- images Common images for the portal
|
+-- menu Resources for MenuService applet
| (Collaborative Components API)
|
+-- META-INF Standard Java MANIFEST.MF for the
| portal Web application
|
+-- peopleawareness Resources for the people awareness features
Chapter 3. Directory structure 175
|
+-- screens Screen JSPs for the portal
| |
| +-- markup_name Subdirectory for each markup type
|
|-- skins Skin JSPs for the portal
| |
| +-- markup_name Subdirectory for each markup type
|
|-- themes Theme JSPs for the portal
| |
| +-- markup_name Subdirectory for each markup type
|
+-- virtualportal XMLAccess file for setting up a virtual portal
|
+-- WEB-INF Protected resources for the portal Web application
|
+-- wts JavaScript resources for Transcoding Technology
The following directories contain resources for customization. Resources for
all other directories in the portal Web application directory structure must
not be modified.
v /doc
v /html
v /images
v /screens
v /skins
v /themes
v /virtualportal
Lotus Domino directory structure (domino_server_root and
domino_data_root)
Throughout this documentation, the install location for the Lotus Domino server
software is noted as domino_server_root, which is the install root.
The following table shows the default location if it is not otherwise specified
during installation:
Operating system Location
z/OS /usr/lpp/lotus (install root)
The Lotus Domino server data directory is noted as domino_data_root, which is the
config root.
The following table shows the default location of the Domino data directory if it is
not otherwise specified during installation:
Operating system Location
z/OS /usr/lpp/lotus/data (config root)
Directories for languages
The following shows the languages supported by WebSphere Portal and the
directories used for storing locale-specific resources. These directories are used in
portlet Web application directories and in the WebSphere Portal enterprise
176 Troubleshooting guide
application (themes, skins, and other Web application resources).
Language
(locale) Directory
Language
(locale) Directory
Language
(locale) Directory
Arabic /ar Hungarian /hu Romanian /ro
Catalan /ca Italian /it Russian /ru
Czech /cs Hebrew /iw Slovak /sk
Danish /da Japanese /ja Slovenian /sl
German /de Korean /ko Swedish /sv
English /en Dutch /nl Thai /th
Greek /el Norwegian /no Turkish /tr
Spanish /es Polish /pl Ukrainian /uk
Finnish /fi Portuguese /pt Simplified
Chinese
/zh
French /fr Brazilian
Portuguese
/pt_BR Traditional
Chinese
/zh_TW
Chapter 3. Directory structure 177
Chapter 4. Notices and trademarks
Copyright IBM Corporation 2000, 2007.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted
by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this
documentation in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply
that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user’s responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this documentation. The furnishing of this documentation does not
give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OR CONDITIONS OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states
do not allow disclaimer of express or implied warranties in certain transactions,
therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
© Copyright IBM Corp. 2000, 2006 179
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk. Licensees of this program
who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other
programs (including this one) and (ii) the mutual use of the information which has
been exchanged, should contact:
Vice President
Intellectual Property & Licensing
North Castle Drive
Armonk, New York 10504
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this documentation and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.This
information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples may include
the names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
Trademarks and service marks
The following are trademarks in the United States, other countries, or both.
AIX®, DB2®, IBM, the IBM logo, i5/OS®, OS/390®, OS/400®, RACF®, RS/6000®,
System i5™, System p, System z, Tivoli, WebSphere, and z/OS are trademarks of
the IBM Corporation in the United States, other countries, or both.
Lotus, Notes®, Domino, QuickPlace, Sametime, Lotus Discovery Server™ are
trademarks or registered trademarks of IBM Corporation and/or Lotus
Development Corporation in the United States, other countries, or both.
180 Troubleshooting guide
Solaris, Java™, and all Java-based trademarks and logos are trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
Microsoft®, Windows®, Windows NT®, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Linux® is a registered trademark of Torvalds in the United States, other countries,
or both.
Intel®, Intel Inside® (logos), MMX and Pentium® are trademarks of Intel
Corporation in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks
of others.
See www.ibm.com/legal/copytrade.html for additional trademarks.
Chapter 4. Notices and trademarks 181
Readers’ Comments — We’d Like to Hear from You
Portal for z/OS
Troubleshooting guide
Version 6.0
We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy,
organization, subject matter, or completeness of this book. The comments you send should pertain to only the
information in this manual or product and the way in which the information is presented.
For technical questions and information about products and prices, please contact your IBM branch office, your
IBM business partner, or your authorized remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use
the personal information that you supply to contact you about the issues that you state on this form.
Comments:
Thank you for your support.
Submit your comments using one of these channels:
v Send your comments to the address on the reverse side of this form.
If you would like a response from IBM, please fill in the following information:
Name
Address
Company or Organization
Phone No. E-mail address
Readers’ Comments — We’d Like to Hear from You
����
Cut or FoldAlong Line
Cut or FoldAlong Line
Fold and Tape Please do not staple Fold and Tape
Fold and Tape Please do not staple Fold and Tape
NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES
BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation
Information Development
Department R0JA
P.O. Box 12195
Research Triangle Park, NC 27709-9990
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
__
_