Troubleshooting administration

 

Troubleshooting issues related to using the portal

This section describes problem that can occur when using or administering the portal.

 

No pages display in the portal (Unix installations with DB2)

If you selected the option to deploy the base portlets (the administration and customization portlets used by the portal) during the portal installation, but no pages are displayed when you open the portal and the following error messages are in the installation log files for the database, there is a shared memory problem with DB2 and the WebSphere Application Server datasources: 

com.ibm.wps.util.DataBackendException: Error during database access!

Nested Exception is com.ibm.websphere.ce.cm.StaleConnectionException:
[IBM][CLI Driver] SQL1224N A database agent could not be started to service a request,
or was terminated as a result of a database system shutdown or a force command.
SQLSTATE=55032

On Unix installations, you cannot use the WebSphere Portal database directly. Instead, define a local alias for the database. The alias connects to the WebSphere Portal database using a TCP/IP connection. For instructions, see the WebSphere Portal Information Center. Search for the instructions for configuring DB2.

 

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. To log in as different users on the same client, use one of the following methods to avoid this problem:

 

When modifying user information via WebSphere Portal, unexpected results could occur

When modifying user information via WebSphere Portal, if you receive the error "Backend storage system failed. Please try again later." or the user attributes are not updated in LDAP, it might mean that the default tuning parameters for use with DB2 and IBM Directory Server need to be adjusted.

The default DB2 parameters are: 

APP_CTL_HEAP_SZ 128
APPLHEAP_SZ 128

The parameters above are too small for IBM Directory Server and WebSphere Portal on AIX with 2000 user entries.

The HEAP size of UDB is required when updating or inserting data. WebSphere Portal spawns heavy transactions to the LDAP server in any phase, especially changing user attributes, which spawns several updates and inserts. To prevent this problem, the following WebSphere Portal tuning is required: 

su -ldapdb2
db2 -c update db cfg for ldap using APP_CTL_HEAP_SZ 1024
db2 -c update db cfg for ldap using APPLHEAP_SZ 1024

 

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.

If this problem occurs, the user should log off and then log in again. Then the problem will not occur again.

 

A portlet does not appear in your portal

Ensure that:

 

Portlet contents are blank

Make sure the enterprise application is started by using the application server's administrative console. 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:

 

A portlet is not accessible after its portlet application has been updated

When a portlet application is updated, the updated portlet or portlets might be temporarily inaccessible. If this happens, log off and log in again to the portal.

 

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. Refresh the Web browser by doing one of the following:

 

User or user group search can time out or return too many results

When performing a search that can return a large number of users or user groups, the search might time out or return more results than the system can handle. Searches can be set to automatically return a specific number of maximum results or time out after a specified time. See Manage users and groups for details on setting this configuration.

 

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. If this occurs, modify the portlet by adding the following configuration parameter and value: 


com.ibm.wps.portlet.action.redirect = true

This allows the page and portlet to be reloaded without the action parameters in the URL. You can add and set configuration parameters using Administration then click Portlets then click Manage Portlets. Select the portlet to be modified and click Modify parameters.

 

Logging in as two users with a Mozilla browser continues to show one user

Mozilla browsers that come from the same IP address share a common WebSphere Portal session. If a user logs in with two different user IDs at the same time, the browser continues to use the same user, and there is no indication which user is actually logged in to WebSphere Portal. For example, if a user logs in as UserA in one browser window and UserB in another browser window, both windows are UserB, and all content and settings displayed belong to UserB.

If you want to login as a different user with a Mozilla browser, close all browser instances before logging in as the alternate user.

 

Parallel portlet rendering does not work when Work Manager is not found

If a Work Manager is not created during the portal installation, the portal gives the following message:

  PEEX0100E Unable to find workload manager wm/wpsWorkmanager

This error message indicates that the Work Manager was not created during portal installation. This can have the following reasons:

As a result, parallel portlet rendering (PPR) does not work. The PPR component logs the error message PEEX0100E as given above. This message also means that the initialization of the parallel rendering process failed. In the case of this error parallel portlet rendering is turned off automatically. However the portal continues to operate properly without this component. All portlets are rendered sequentially.

For solution of this problem, make sure that the prerequisites to run the PPR component successfully are installed before the installation of the portal. These are as follows:

  1. The application server is installed including PME.

  2. PME includes the Asynchronous Beans required to create a Work Manager.

  3. A Work Manager named wm/wpsWorkmanager was created during the portal installation.

 

Cannot navigate portal Administration

Changing the setting of the navigation.expansion.defaultstate Configuration Service parameter to false causes the side navigation nodes to be collapsed by default. This also causes navigation in the portal Administration not to function properly. The left navigation for Administration (which is the LayeredContainer.jsp for the Echo skin) was designed to not use the portal's expand/collapse mechanism for node display, but instead to display only the children in the current selection path. This requires the default expansion state to be true.

If you want side navigation to be collapsed by default, you have two options for fixing the navigation in Administration.

Change the theme for Administration to Admin

This renders the first level administrative pages (for example, Portlets or Access - which are actually level 2 navigation nodes) as tabs horizontally underneath the banner and places the subordinate level of administrative pages (Install, Users and Groups, for example) vertically to the side. Use Manage pages to edit the properties for Administration and change the theme.

 

Replace the Echo skin's LayeredContainer.jsp with the default LayeredContainer.jsp

This renders the Administration pages vertically to the side with expand and collapse icons (+ and -). To replace the Echo skin's LayeredContainer.jsp, follow these steps.

     

  1. Backup LayeredContainer.jsp for the Echo skin to a safe location. This file is located in the was_root/installedApps/node_name/wps.ear/wps.war/skins/html/Echo/ directory.

     

  2. Copy the file LayeredContainer.jsp from 
    was_root/installedApps/node_name/wps.ear/wps.war/skins/html/
    to 
    was_root/installedApps/node_name/wps.ear/wps.war/skins/html/Echo
    .

     

  3. Edit the new LayeredContainer.jsp in the Echo skin and change 
    <%@ include file="BidiInclude.jsp" %>
    to 
    <%@ include file="../BidiInclude.jsp" %>

 

Problem: Portal URLs need authentication for anonymous users

The new URL Function creates Portal URLs with the protected URI, which by default is /myportal. This forces a need for authentication even if the anonymous user is granted access to the label, page and New URL.

Scenario:

A user creates a new label, Label A, under the Context Root of Portal (this is the same level as the "My Portal" label). An administrator then creates a page under Label A, for example, Page A. The administrator then adds portlets to Page A. At this point the page is still not visible to an anonymous user because its URL must be created so that its link displays Label A and Page A. To create the proper URL the administrator now accesses...

Administration | Manage Pages | My Portal | New URL

The new URL that is created is a link to Label A. In this example, the radio button "A link to the following Portal page" is selected. The anonymous user is now added to the user role of the new URL that was created. This will now allow the anonymous user to be able to view a link to Label A. However, when the link is selected the portal server will still prompt the user to enter valid credentials.

Cause:

The user is prompted to enter valid credentials because the "New URL" button creates all links in the form /wps/myportal/xxxx/yyyyy. By default, the /myportal URI is protected, which means that a user must authenticate to be able to view the contents.

Solution:

Instead of selecting the radio button "A link to the following Portal page," select the radio button "A link to a webpage with the following URL."

To then create a URL for Label A and Page A, first create a URL Mapping for Label A and Page A. To create a URL mapping, perform the following steps:

  1. Log in to WebSphere Portal as the administrator.

  2. Go to Administration > Portal Settings > URL Mappings.

  3. Choose New Context and provide a name for Label A, for example "TestLink."

  4. Select OK.

  5. Choose the Edit Mapping icon for TestLink and map it to Label A.

  6. Label A should now be accessible by the URL http://hostname/wps/portal/TestLink.

Now when creating a New URL, you can use the external link of http://hostname/wps/portal/TestLink in order to avoid the authentication requirement by avoiding the /myportal URL.

 

Problem: Document Search portlet fails on anonymous page

If you put the Document Search portlet on an anonymous page so that users can use it without having to log in to the portal, the portlet does not work.

Solution:

You need to enable public sessions for your portal. The reason is that the document search portlet needs a valid session for its run time, and by default, sessions are not enabled on anonymous pages in the portal. By default, sessions are only created when a user authenticates and logs in to the portal server.

To enable public sessions, edit the file wp_root/shared/app/config/services/NavigatorService.properties and set the public.session parameter to true. Restart both WebSphere Application Server and WebSphere Portal for your changes to take effect.

 

Troubleshooting failed attempts to access the portal

This section describes problems that might occur when a user tries to log in to the portal.

 

Login fails with a user ID that contains special characters

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 administration server and all application servers. For more detail, see the documentation for WebSphere Application Server.

 

Problems 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. In either case, there are two possible solutions.

 

Unable to log in to 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. Set the correct time on the client system clock.

 

User is logged out of the portal

There are two reasons a user can be logged out by the portal:

The following sections provide solutions for both problems.

 

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.

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:

    • For the Web container level:
      1. Click Servers > Application Servers.
      2. Select a server from the list of application servers.
      3. Under Additional Properties, click Web Container.

    • For the enterprise application level:
      1. Click Applications > Applications.
      2. Select an applications from the list of applications.

    • For the Web module level:
      1. Click Applications > Enterprise Applications.
      2. Select an applications from the list of applications.
      3. Under Related Items, click Web Modules.
      4. Select a Web module from the list of Web modules defined for this application.

  3. 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.

 

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 reauthenticate 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 Securtiy > 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.

 

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. 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: 
      wp_root/config/work/recoverHTML.xml

  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 wp_root/bin directory.

  5. Run the XMLAccess command against the XML file you created. On a Windows system, for example: 
      xmlaccess -in C:\WebSphere\PortalServer\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.

 

Browser returns an invalid syntax error

Some browsers might return a page not found - invalid syntax error when attemping to access WebSphere Portal. 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.

 

Troubleshooting issues related to national language support

This section describes problems that can occur when viewing different languages with WebSphere Portal.

 

Problems with browsers displaying DBCS characters

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

 

Problem 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. See the Requirements section in the Information Center to view a list of other Web browsers that you can use.

 

Problems with Microsoft Internet Explorer in a Japanese environment

See also