Troubleshooting the XML configuration interface

The following gives administrators information to assist them with preventing, identifying, and correcting possible problems that might occur when using the XML configuration interface.

Error response "Unknown schema or reference" when importing an XML file
Unexpected syntax errors
Message "XMLC0091E: The servletref attribute is required to create a portlet clone . . ." appears
Message "XMLC0049E: Input syntax error ...", followed by "org.xml.sax.SAXParseException: cvc-elt.1: Cannot find the declaration of element 'request'."
Message "LDAP: error code 49 - Invalid Credentials" is misleading
Import of pages might fail to re-create wires
User data not exported as specified
Message "XMLC0142E: Unique name unique_name is already used in the portal."
XML configuration interface tasks result in errors during install and uninstall when using HTTP server port
Cannot use the XML configuration interface if it is externalized in security
Re-creating and browsing a page can result in an application error
Re-import of WAR files might fail due to incorrect path information
XML import might fail with out-of-memory error

Problem: Error response "Unknown schema or reference" when importing an XML file

The attempt to import an XML file results in an error response that contains the following message:

     <message>com.ibm.wps.command.xml.XmlFormatException: XMLC0050E: 
        Input syntax error: the XML input does not conform to the XML schema</message>
     <message>org.xml.sax.SAXException: 
        Unknown schema or reference -//IBM//DTD Portal Configuration 1.1//EN  --  PortalConfig_1.1.dtd</message>

Solution: Your XML file is in the format used by WebSphere Portal V4.1 or 4.2. You need to convert your input file to the new format used by WebSphere Portal V5.1.

Problem: Unexpected syntax errors

Although the XML input file seems to be valid, inexplicable syntax errors are reported, for example unclosed XML tags.

Solution: A possible reason is that your files are being truncated before they are processed by the portal. This can typically occur for two reasons:

Your input file contains invalid UTF-8 characters. A good way to check your input files is to view them with Microsoft Internet Explorer. Microsoft Internet Explorer shows errors if your input contains invalid characters.
You have a problem with your HTTP communication setup, for example, your input is relayed through a HTTP server that truncates it. You can check for communication problems by specifying the -echo command line parameter when you call the XML configuration interface tool. When this parameter is specified, your request is not processed, but simply returned as it is read by the server. If the output is different from your input file, your request was modified somewhere along the communication path.

Problem: Message "XMLC0091E: The servletref attribute is required to create a portlet clone . . ."

The attempt to deploy a portlet in a XML request results in the error message given above.

Solution: There is a mismatch between the name, uid and refid attributes that are given in the XML request and those that were specified in the portlet.xml deployment descriptor for your portlet or portlet application. Therefore XML processing tries to create new portlets where it should only update those that have been created as part of the WAR file deployment. Use the Install portlet to deploy your WAR file, export the portlet application (package), and compare the export with your XML request, or compare your XML request with the portlet.xml. Make sure that the names and IDs for portlets and portlet applications are identical.

Problem: Message "XMLC0049E: Input syntax error ...", followed by "org.xml.sax.SAXParseException: cvc-elt.1: Cannot find the declaration of element 'request'."

The attempt to import an XML file results in the error messages given above.

Solution: Your XML file contains an invalid schema or namespace declaration. Check the request element for typographical errors or missing attributes. The request must have the following form:

     <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:noNamespaceSchemaLocation="PortalConfig_1.2.xsd"
          ...>

Problem: Message "LDAP: error code 49 - Invalid Credentials" is misleading

If you try to connect to the portal with security and LDAP enabled, but if the LDAP server is not available, the following error message is returned in the XML response file:

     
     com.ibm.websphere.wmm.exception.WMMSystemException: 
     The following Naming Exception occurred during processing: 
     "javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials]".

This message can be misleading.

Solution: The LDAP error message Invalid Credentials means that the user name or password are wrong. It can also mean that the LDAP server is not available at all.

Import of pages might fail to re-create wires

When you use the XML configuration interface to import pages that contain wires between cooperative portlets, the wires might not get created during the import. When the portal pages are imported, the portlet actions and properties required by the wires are registered, but the wires themselves might not get created.

Solution: To import existing wires from one portal to anther, proceed by the following steps:

Export the page that contains the wires from the original portal.
Make sure that the portlets for the page are already deployed on the target portal for the XML import.
Run the XML script for importing the page. The page will be created successfully, but the subsequent step for creating the wires might fail with errors.
View the newly created page in the portal.
Run the XML import script once more. This time the wires are created successfully.

If you enabled the portlets on the page for cooperation by the declarative approach, that is by using a WSDL file to declare the actions and properties, you can use a simpler procedure:

Before you run the XMLAccess import task, edit the file ConfigService.properties that is located in the following directory:
- UNIX: wp_root/shared/app/config/services
- i5/OS: wp_user_root/shared/app/config/services
- Windows: wp_root\shared\app\config\services
Set the host.name and host.port.http properties to the hostname and http port of the target portal server for the import. (These values might have been set by the portal installation already. In this case you do not need to update them.)

The import of the pages and the creation of the wires should work in one step.

For more information about cooperative portlets refer to Known issues and restrictions with cooperative portlets.

Problem: User data not exported as specified

User name data are not exported as specified by the user tag attributes firstname, lastname, or name. The reason is that the values of some attributes of the tag user correspond to settings in included parameter tags. If you include both in your export request, but specify different values for them, then the value set by the parameter tag overwrites the value set by the attribute, and is exported as the attribute.

Solution: Use only one of the two ways to specify the user data, either the attribute or the parameter tag. For more information about this, see the description of the user tag under XML reference, Types of portal resources.

Problem: Message"XMLC0142E: Unique name `unique_name` is already used in the portal."

One or more nested elements were not created properly.

Solution: When you create a nested element, for example a component, with a uniquename attribute, the whole hierarchy upward from that element must also have uniquename attributes. Example XML export request snippet:

     <content-node ...
          <component uniquename="component_1"...
               <component uniquename"component_2"...
                    <component uniquename"component_3"...
                         . . . . .
                    </component>
               </component>
          </component>                       
     </content-node>

Problem: XML configuration interface tasks result in errors when using HTTP server port

XML configuration interface tasks may result in errors if you do not use the direct port.

Solution: When you process tasks using the XML configuration interface, use the direct port, for example, 9081, rather than going through the HTTP server on port 80.

Problem: Cannot use the XML configuration interface if it is externalized in security

If the virtual resource XML_ACCESS that represents access to the XML configuration interface is put under protection of an external security manager, you can no longer use the XML configuration interface.

Solution: If the access rights of WebSphere Portal are externalized to an external security manager, such as TAM, make sure that the XML configuration interface virtual resource is not externalized.

Problem: Re-creating and browsing a page can result in an application error

If you delete a page with an object ID and use the XML configuration interface to re-create the same page with the same object ID, you might receive an application error when browsing that re-created page.

Example scenario: You delete a page with an object ID. You use an XML import request to re-create the same page with the same object ID. When you browse the newly re-created page, you receive an application error.

Cause: When you delete a page, the portal marks the page for deletion, but does not actually delete the page until a later point in time when the scheduled cleanup service runs. Until that time remainders of the deleted page exist in the portal. They can interfere with the newly created page and result in the application error.

Solution: To avoid this, run the cleanup service task before re-creating the page with the XML configuration interface. After you have deleted a page with an object ID, do not re-create the same page with the same object ID without first running the cleanup service task. As an alternative you can also configure the cleanup service for immediate deletion. This deletes portal pages immediately when you delete them.

For more details about how you can use the XML configuration interface to perform a cleanup refer to the XML reference under the task tag.
For more details about the cleanup service and how to configure it, refer to Delayed cleanup of deleted portal pages.

Problem: Re-import of WAR files might fail due to incorrect path information

The XML import of previously exported WAR files might fail with a File not found condition due to incorrect path information.

Cause: When you deploy a Web application, the path location information of the WAR file is not persisted in the portal database. An XML import assumes the following portal default path locations:

UNIX: wp_root/installableApps
i5/OS: wp_user_root/installableApps
Windows: wp_root\installableApps

Therefore, if the path location of your WAR files does not match the default path, the XML configuration interface cannot locate your WAR files.

Solution: To resolve the problem, proceed by either one of the following options:

Copy the WAR files that you want to import to the following default path location:
- UNIX: wp_root/installableApps
- i5/OS: wp_user_root/installableApps
- Windows: wp_root\installableApps
Edit the XML file that resulted from the XML export, and replace the default path by the path on your portal installation. The location is referred to by the <url> subtag.

For information about how to use the <url> subtag with the <web-app> tag, refer to Importing WAR files.

Problem: XML import might fail with out-of-memory error

An XML import of portal resources might fail with an OutOfMemoryError.

Cause: This error results from a limited heap size.

Solution: Proceed by the following steps:

Start server1 and log in.
Navigate to Servers, > Application Servers > WebSphere_Portal > Process Definition > Java Virtual Machine.
Determine the configured maximum heap size; for example, this might be 512 MB.
Increase the maximum heap size, for example to 1024 MB.
Restart your portal.
Run the XML import script again. The OutOfMemoryError should disappear.