Websphere Portal Troubleshooting PDF

WebSphere Portal for z/OS

Version 6.0

Troubleshooting guide

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.

ContentsChapter 1. Troubleshooting . . . . . . 1Tools 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 . . . Contact support . . . . . . . . . . . General installation troubleshooting worksheet General configuration troubleshooting worksheet . . . . . . . . . . . . General customization troubleshooting worksheet . . . . . . . . . . . . General runtime troubleshooting worksheet . General programming troubleshooting worksheet . . . . . . . . . . . . . 149 . 151 152 . 153 . 154 . 156 . 157

Chapter 2. Additional resources . . . 161Resources for learning Additional resources Additional resources Additional resources Additional resources Additional resources Directory structure . . . . . . . . . . . . . . . for planning . . for installation . . for administration for development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 161 162 165 165 166 171

Chapter 3. Directory structure . . . . 175 Chapter 4. Notices and trademarks 179

Copyright IBM Corp. 2000, 2006

iii

iv


Chapter 1. TroubleshootingWelcome 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 diagnosticsThere 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 AssistantIBM 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 tracingIf 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 questionsHow 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 logsThis 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 filesWebSphere 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 filesThe WebSphere Portal installation log files are in the following directory: v z/OS: portal_server_root/log

2


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 cmInit.log, jcrdb2zos.log, yourLocationName.log Description Problem symptoms

Contain trace information Check these logs if there are generated during JCR (that problems during JCR is, the DB2 Content Manager configuration. 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.)

ConfigMessages.log

Contains messages that are Check this log for errors generated during installation. generated during installation. The messages in this file are translated for the language that is specified during installation. Contains trace information generated by WebSphere Portal installation. Contains trace information generated during database transfer. Contain trace information generated during the execution of the installation jobs. Contains system output during installation and runtime. Check this log for errors generated during installation. Check this log if there are problems during database transfer. Check these files if there are problems with a specific installation step. Check this log if there are access problems during installation or errors in system software.

ConfigTrace.log

DatabaseTransfer.log.n

Job logs of installation jobs (such as EJPSCFG1, EJPSBCA, and so on). z/OS Console log

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 filesThe 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 MigrationTrace.log Description Contains trace information that is generated by the migration process. Contains messages that are generated during migration. The messages in this file are translated for the language that is specified during installation. Problem symptoms Check this log if migration stops before successful completion. Check this log for errors generated during migration.

MigrationMessages.log

en.runningNumber.log, trace.runningNumber.log

Contains trace messages of Check this log for errors the Web Content generated during migration. Management migration tasks. These files are located in the directory: portal_server_root/wcm/ migration/log.

Related informationv Chapter 1, Troubleshooting, on page 1

WebSphere Portal run-time logsUsing WebSphere Portal log filesIBM 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 fileThe 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


Note: The trace strings beginning with com.ibm.wps.* are extensions in the IBM portlet API.Area of concern Access Control When to use Trace string Additional comments The traces are easier to evaluate while WebSphere Portal usage is low. Important: Enabling this logger creates very large log files.

Enable this tracer if you com.ibm.wps.ac.*=all 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.

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 Use to turn on all command trace loggers. 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.commands.*=all com.ibm.wps.model.*=all: The traces are easier to com.ibm.wps.composition.*=all evaluate while WebSphere Portal usage is low. Important: Enabling this logger creates very large log files.

Command Composition Model

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 Deals with generated SQL statements and the internal flow in the WebSphere Portal database layer. Use to enable all engine trace loggers. com.ibm.wps.datastore.*=all: Important: Enabling this com.ibm.wps.services.datastore.*=all create very large logger will log files. com.ibm.wps.engine.*=all 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: 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.

Database

Engine General

com.ibm.wps.pe.PortletRenderTimeLoggingHelper=info Mail Service Mapping URLs Use to diagnose problems with the Mail Service. Use to diagnose problems with the user-defined mappings of URLs com.ibm.wps.services.mail.*=all com.ibm.wps.mappingurl.*=all: com.ibm.wps.command.mappingurl.*=all


5

Area of concern Personalization

When to use

Trace string

Additional comments

com.ibm.websphere.personalization.*=all When Personalization is com.ibm.dm.pzn.ui.*=all installed outside of a WebSphere Portal server, Personalization will log using WebSphere Application Server tracing with the same trace strings. com.ibm.wps.pdm.*=all=enabled com.ibm.content.*=all=enabled com.ibm.icm.*=all=enabled Use to turn on all WebSphere Portal Search messages. Enable to obtain messages about URLs that are discovered by the crawler but could not be fetched and indexed for different reasons. Enable to obtain messages about the crawling process. Enable to obtain messages about failures that happen during a crawl. com.ibm.portal.search=all For detailed information refer to Logging and tracing in Portal Search. com.ibm.portal.search.notIndexed=all

Document Manager

WebSphere Portal Search

com.ibm.portal.search.crawler=all com.ibm.portal.search.crawler.failure=all

Enable to obtain messages com.ibm.portal.search.index=all about the indexing process. Enable to obtain messages about failures that happen during the indexing process. Portlet Container com.ibm.portal.search.index.failure=all

com.ibm.wps.pe.pc.*=all: org.apache.jetspeed.portlet.Portlet=all javax.portlet.Portlet=all com.ibm.wps.pe.ext.*=all: com.ibm.wps.pe.factory.*=all: com.ibm.wps.pe.om.*=all: com.ibm.wps.pe.util.*=all com.ibm.wps.pe.mgr.*=all: com.ibm.wps.services.deployment.*=all: com.ibm.wps.command.applications.*=all: com.ibm.wps.command.portlets.*=all Use to diagnose problems with portlets. com.ibm.wps.portlets.*=all:Enables tracing for all org.apache.jetspeed.portlet.PortletLog=all place portlets. Therefore, the suspect portlet on a separate page for testing.

Portlet Environment

Deployment

Portlets

Scripting Interface

Use this trace string to com.ibm.wps.scripting.*=all: traces are easier to The diagnose problems with the evaluate while WebSphere Portal Scripting Interface, Portal usage is low. or with application Note: Enabling this logger interface scripting, and the can create large log files execution of such scripts. fast.

6


Area of concern Selfcare

When to use Use to diagnose problems with user registration and profile editing.

Trace string

Additional comments

com.ibm.wps.services.puma.*=all: logger if there are Use this com.ibm.wps.puma.*=all errors in the sign-up, Edit My Profile, and the Manage Users and Groups portlets. com.ibm.wps.services.registry.EventHandlerRegistry=all: com.ibm.wps.services.events.*=all

Services: EventBroker Services: Finder Services: Loader Use for debugging the resolution of file names. Use to trace the dynamic class loading performed by this service.

com.ibm.wps.services.finder.*=all com.ibm.wps.services.ServiceManager=all

ServicesNaming

Use to debug the lookup of com.ibm.wps.services.naming.*=all objects by the naming service. Use to diagnose problems with parts of page aggregation and display. com.ibm.wps.services.navigator.*=all

ServicesNavigator

ServicesRegistry

Use to view the policies of com.ibm.wps.services.registry.*=all the internal portlet object caching and watch it reload its content. Use for switching on tracing for all services. Use to turn on all SSO tracer loggers listed after this trace logger. com.ibm.wps.services.*=all 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.

Services SSO

WSRP administration

Use to diagnose problems com.ibm.wps.command.wsrp.*=all: com.ibm.wps.wsrp.cmd.*=all occurring during the administration of Web Services for Remote Portlets (WSRP) with WebSphere Portal. Use to diagnose problems com.ibm.wps.wsrp.consumer.*=all occurring during the use of WSRP with WebSphere Portal as a Consumer. Use to diagnose problems com.ibm.wps.wsrp.producer.*=all occurring during the use of WSRP with WebSphere Portal as a Producer. com.ibm.wps.command.xml.*=all

WSRP Consumer

WSRP Producer

XML configuration interface Use to diagnose problems with the XML import/export of WebSphere Portal configurations.



7

WebSphere Application Server tracing and log filesIBM 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.


Member Manager tracing filesUsing 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 loggingThe 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


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 loggingWebSphere 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 loggingWebSphere 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 filesBy 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 locationWhen 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


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 fileBy 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 formatIf 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 messagesChapter 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 informationv v v v v v Portal configuration Administering WebSphere Portal logs on page 2 Designing Chapter 1, Troubleshooting, on page 1 Directory structure on page 168

Transcoding Technology logging and tracingTranscoding 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


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 filesIBM 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


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: com.ibm.workplace.wcm.services.content.* Description: 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.


15

Trace setting:

Description:

com.ibm.workplace.wcm.domain.transformers.controllable.controllabletype any of the You can enable tracing for 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 PlaceholderCmpntTransformerTroubleshooting guide

16

v PlutoSubscriberTransformer v PlutoSyndicatorTransformer v PrefixPathCmpntTransformer

Trace setting:

Description:

com.ibm.workplace.wcm.domain.transformers.controllable.* the tracing for all controllable This enables 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 loggingIBM 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.


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 SiteAnalyzerSessionLogger.isLogging Description and Activity Logged HTTP requests that include the URLs: /Command/Login /Command/Logout

18


WebSphere Portal Server Analysis Logger SiteAnalyzerUserManagementLogger.isLogging

Description and Activity Logged HTTP requests that include the URLs: /Command/UserManagement/CreateUser /Command/UserManagement/DeleteUser /Command/UserManagement/CreateGroup /Command/UserManagement/DeleteGroup HTTP requests that include the URLs: /Page/* /Command/Customizer/CreatePage /Command/Customizer/EditPage /Command/Customizer/DeletePage HTTP requests that include the URLs: /Portlet/* HTTP requests that include the URLs: /PortletAction/* HTTP requests that include the URLs: /Error/Portlet /Error/Page The referrer field points to a portlet name or a page name. Examples of such referrer fields are: http://your.server.name/Portlet/1/PortletName http://your.server.name/Page/1/PageName HTTP requests that include the URLs: /ApplicationAction/*

SiteAnalyzerPageLogger.isLogging

SiteAnalyzerPortletLogger.isLogging SiteAnalyzerPortletActionLogger.isLogging SiteAnalyzerErrorLogger.isLogging

SiteAnalyzerApplicationActionLogger.isLogging=true

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:


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 9.37.3.88 Log Field Name and Explanation 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 ( - ). username The user ID for the client. If the user ID is not known, the field is set to the the hyphen character ( - ). date:time: timezone The date and time of the HTTP request. request The HTTP method, the URL of the requested resource and the version of HTTP used by the client. statuscode The HTTP status code for the request. bytes The number of bytes of data transferred from the client as part of the request. A value of -1 means unknown. 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: user_agent The type of Web browser used by the client. 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.

customer2

[10/APR/2002:21:33:16 +0000] "GET /Portlet/146/Welcome_Portlet? 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"

Search the product documentation for a solutionThis 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 WebSphere Portal installationThis 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 supportWhen 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 installedIf 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 messageInstallation 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 informationWebSphere 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


v z/OS: ./genHistoryReport.sh

Problem: Java processes continue to runWhen 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 failsSolution: 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 installationSolution: 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 PortalIf 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: wpsdbJDBC 2. On the portal machine, delete the WebSphere Portal directory manually. 3. Restart the installation.

Problem: Installation fails due to insufficient disk spaceSolution: 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 deployIf 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/binxmlaccess -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 failsIf 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


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 ServerIf 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 installationIf 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.readExecuteIntern 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;


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/OSDuring 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 jobsDuring 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 wizardUsing 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


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 attributesProblem: 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:


27

dogert dish html

Sample XML script file snippet export2: dogert dish html

From the two exports above, ReleaseBuilder generates the following differential file:

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 configurationWhen attempting to import the entire portal configuration, the transfer will be successful with some warnings similar to, but not limited to, the following: 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] 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]

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 clusterIf 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


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/AccessBeanWhen 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 errorWhen attempting to federate a WebSphere Portal node, the addNode command might fail with the following error:


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 failProblem: 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/c [wsadmin] org.apache.soap.SOAPException: [SOAPException: faultCode=SOAP-ENV:Client; msg=Br

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 interfaceProblem: The XML configuration interface fails with the following error when you try to set global settings in a clustered environment. com.ibm.wps.command.xml.XmlCommandException: EJPXA0043E: An error occurred while creating or updating the resource. [global-settings] com.ibm.wps.command.CommandException: EJPEB0002E: An exception occurred. java.security.PrivilegedActionException: java.lang.NullPointerException

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 errorWhen 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


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 managers administrative console. 2. Click Servers Application Servers, and select the server that corresponds to the cluster member that is failing to start. 3. 4. 5. 6. Click Ports, and then click DCS_UNICAST_ADDRESS. Modify the port number to a unique port number. Click Apply, and save your configuration changes. Restart the cluster member.

Troubleshooting databasesThis 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 databaseWhen 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.


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/OSIf 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/OSThe 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 domainsWhen 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


Problem: Database Transfer fails on Oracle during LikeMinds table creationWhen 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 CloudscapeProblem: 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/clouds

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 localeProblem: 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 securityThis 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 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 36Chapter 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 workIt 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 characters display incorrectlyIn 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 as >. Other non-alphabetical characters like &, single quotes, and double quotes appear as intended. Disabling CSS allows the characters to appear as intended. Characters such as 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 users application (the victim). If the

34


secure program does not protect the victim, the victims 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 v v v v Attacks might be persistent through poisoned cookies Attacker might access restricted web sites from the client Domain-based security policies might be violated Use of less-common character sets might present additional risk 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 VaultSolution: 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 NameMember 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 browserWhen 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 logoutWith 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 ModuleSolution: 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 installationUnder 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 users portal session has timed out. The portal then prompts the user to log in again.

36


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 applications session cookie is scoped to that application only: 1. Log in to the WebSph

Websphere Portal Troubleshooting PDF

Documents

Transcript of Websphere Portal Troubleshooting PDF

Configuring your Solution with WebSphere Portal, WebSphere

WebSphere Portal Introduction

WebSphere Portal v6

IBM Websphere Portal Handbook

Coursemill for Websphere Portal

Configuring your Solution with WebSphere Portal, · PDF fileServer and WebSphere MQ December 2003 ... WebSphere Portal, WebSphere Application Server, and WebSphere MQ Document version

WebSphere Portal & Rich Internet Applications

Referencias proyectos WebSphere Portal

Chapter 2 WebSphere Portal Server V6: Architecture ... · WebSphere Portal Server: ... until you complete the migration task to use LDAP server. ... (server1) and (2) WebSphere Portal

IBM WebSphere Portal © 2008 IBM Corporation IBM WebSphere Portal 6.1 Overview.

A step-by-step guide to configuring a WebSphere Portal v6 ...websphereportalguru.com/common_files/Setup a portal... · WP – WebSphere Portal WPS – WebSphere Process Server WAS

20040921 Serviceorientierte Architektur für WebSphere und WebSphere Portal

Troubleshooting Guide - IBM · Troubleshooting Guide GC14-7521-00. ... WebSphere MQ Monitoring agent ... Logging on to Tivoli Enterprise Portal fails and

WebSphere Portal content publishing Installation Guidepublib.boulder.ibm.com/wcmid/mp/v42/doc/en/install.pdf · the WebSphere Portal content publishing wizards and WebSphere Portal

Websphere Portal Social Entitlements

WebSphere Commerce Portal

WebSphere Portal Technical Conference U.S. 2007 WebSphere Portal v6 Migration Rob Holt, WP Migration.

WebSphere Portal Technical Overview

IBM WebSphere Portal - Riverbed · PDF filePERFORMANCE BRIEF IBM WebSphere Portal Riverbed® Steelhead® Appliances Accelerate IBM WebSphere Portal IBM WebSphere Portal

IBM WebSphere Portal 7