Troubleshoot the XML configuration interface

 

+
Search Tips   |   Advanced Search

 

  1. Error response "Unknown schema or reference" when importing an XML file
  2. Unexpected syntax errors
  3. Message "XMLC0091E: The servletref attribute is required to create a portlet clone... "
  4. Message "XMLC0049E: Input syntax error...", followed by "org.xml.sax.SAXParseException: cvc-elt.1: Cannot find the declaration of element 'request'."
  5. Message "LDAP: error code 49 - Invalid Credentials" is misleading
  6. User data not exported as specified
  7. Message"XMLC0142E: Unique name unique_name is already used in the portal."
  8. XML configuration interface tasks result in errors when using HTTP server port
  9. Cannot use the XML configuration interface if it is externalized in security
  10. Re-creating and browsing a page can result in a duplicate key error
  11. Re-import of WAR files might fail due to incorrect path information
  12. XML import might fail with out-of-memory error
  13. WPSconfig command fails when running XML configuration interface
  14. Problems when exporting or importing policies by using the XML configuration interface
  15. Problems when transferring Document Manager
  16. Portlet global state attribute without wire is not exported by XML export
  17. We cannot delete attributes by using the XML configuration interface
  18. User and Group import via the XML configuration interface
  19. ReleaseBuilder ignores deletion of attributes

 

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: Our XML file is in the format used by IBM WebSphere Portal Version 4.1 or 4.2. You need to convert the input file to the new format used by WebSphere Portal V6.0.

 

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 the files are being truncated before they are processed by the portal. This can typically occur for the following reasons:

  1. Our input file contains invalid UTF-8 characters. A good way to check our input files is to view them with Microsoft Internet Explorer. Microsoft Internet Explorer shows errors if the input contains invalid characters.

  2. Some VI editors of UNIX systems cause problems when handling large files. This depends on the implementation of the VI editor. For example, if you use such a VI editor to modify an XML script with more than 40.000 lines, parts of the file contents might get truncated. Use a different editor to modify such large files.

  3. You have a problem with the HTTP communication setup, for example, your input is relayed through a HTTP server that truncates it. In this case we 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, the request is not processed, but simply returned as it is read by the server. If the output is different from the input file, our request was modified somewhere along the communication path.

 

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

  • name
  • uid
  • refid

...that are given in the XML request and those that were specified in the portlet.xml deployment descriptor for the 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...

  1. Deploy the WAR file
  2. Export the portlet application (package)
  3. Compare the export with the XML request or compare the XML request with the portlet.xml.

Verify the names and IDs for portlets and portlet applications are identical.

 

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

 

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.

 

User data not exported as specified

User name data are not exported as specified by the user tag attributes...

  • firstname
  • lastname
  • 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 the 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, see the description of the user tag under XML reference, Types of portal resources.

 

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>

 

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 we process tasks using the XML configuration interface, use the direct port, for example, 10038, rather than going through the HTTP server on port 80.

 

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, we can no longer use the XML configuration interface.

Solution: If the access rights of WebSphere Portal are externalized to an external security manager, such as Tivoli Access Manager, verify the XML configuration interface virtual resource is not externalized.

 

Re-creating and browsing a page can result in a duplicate key error

If you delete a page with an object ID and use the XML configuration interface to re-create the same page with the same object ID, you might receive an error message indicating the operation was aborted because it would have caused a duplicate key value.

Example scenario: You delete a page with an object ID. Use an XML import request to re-create the same page with the same object ID. The import fails with the following message:

The statement was aborted because it would have caused a duplicate key value in a unique or primary key constraint

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

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

 

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:

Therefore, if the path location of the WAR files does not match the default path, the XML configuration interface cannot locate the 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:

  • Edit the XML file that resulted from the XML export, and replace the default path by the path on the 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 Import WAR files.

 

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:

  1. Start server1 and log in.

  2. Navigate to...

    Servers | Application Servers | WebSphere_Portal | Java and Process Management | Process Definition | Java Virtual Machine

  3. Determine the configured maximum heap size; for example, this might be 512 MB.

  4. Increase the maximum heap size, for example to 1024 MB.

  5. Restart the portal.

  6. Run the XML import script again. The OutOfMemoryError should disappear.

 

WPSconfig command fails when running XML configuration interface

Occasionally you might encounter an error where the WPSconfig command fails because of a problem running the XML configuration interface.

Cause: Typically this error results from a problem with the host name and port number configuration in WebSphere Application Server that prevents proper operation of the xmlaccess command. For example, the error message below resulted from an attempt to access an SSO domain that could not be resolved by localhost:

SRVE0017W: A WebGroup/Virtual Host to handle localhost:10038 has not been defined.

Solution: To correct this problem, edit wpconfig.properties and update the value of the XmlAccessHost property with the full host name of the portal server.

 

Problems when exporting or importing policies by using the XML configuration interface

When you use the XML configuration interface to work with policies, the following limitations apply:

  1. The policy-sub-nodes are stored in a separate file. This file can be referenced by an XML script, and that link can be exported and imported by using the XML configuration interface.

  2. Access control for policies is exported only for the base policy-node, but not for the sub-nodes.

  3. The portal ReleaseBuilder does not handle policies.

Cause: This is a known limitation.

Solution: To resolve this limitation, we need to add some manual steps to running the XML export and imports:

  1. After successful export of the policies, copy the separate file that contains the policy-sub-nodes from the source to the target system.

  2. Optional: If you copied that file to a different directory location, adapt the path given for the separate file with the policy-sub-nodes in the XML export result file.

  3. After successful import of the policies, configure access control permissions on the sub-nodes manually by using the Resource Permissions portlet.

 

Problems when transferring Document Manager

When we use the XML configuration interface to transfer a portal configuration that includes the Document Manager application, buttons might be missing from the user interface panels of that application.

Cause: This is a known limitation.

Solution: Add some additional steps after performing the transfer by using the XML configuration interface:

  1. Log in to the WebSphere Application Server Administrative Console.

  2. Select the Document Manager application...

      Applications | Enterprise Applications | Document Manager | Map Security Roles to Users/Groups

  3. Assign the Authenticated role to everyone.

  4. Save the changes.

 

Portlet global state attribute without wire is not exported by XML export

If you export a portlet that has the global state attribute set, but no wires, the global attribute is not exported. Consequently, this attribute is missing after re-import of the XML script.

Cause: The XML configuration interface does not export the global state attribute of portlets.

Solution: To resolve this limitation, use one of the following options:

  1. After the XML import, reset the portlet to global state by using the portal administrative user interface. Select...

    Edit page layout | Wires | Manage Actions

    ...and set the portlet to global state.

  2. Before the XML export, create a wire for the portlet. The XML configuration interface exports the wire. The XML import creates the global attribute for all portlets that have a wire.

 

We cannot delete attributes by using the XML configuration interface

We cannot delete the value for an attribute by using the XML configuration interface.

Cause: This is a known limitation. The XML configuration interface does not allow deletion of attributes.

Solution: We can overwrite the value of the attribute by another value by using the XML configuration interface.

Refer also to ReleaseBuilder ignores deletion of attributes.

 

User and Group import via the XML configuration interface

The XML configuration interface is not intended to perform the import or migration of large user and group populations.

Cause: This is a known limitation. The XML configuration interface does not allow import of large user groups.

Solution: To migrate or transfer large user groups, use tools provided by the LDAP vendor. To import the Access Control on users and groups, you have to only import the group tag without nested member-user or member-group tags. Modify the XML script accordingly.

 

ReleaseBuilder ignores deletion of attributes

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 We cannot delete attributes by using the XML configuration interface.

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 the source system. Sample scenario and files: An example scenario and sample scripts are given in the following.

  1. Create configuration status export1 of the source portal by using the XML configuration interface.

  2. You modify the 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. Create configuration status export2 of the source portal by using the XML configuration interface.

  4. Use ReleaseBuilder to extract the changes between export1 and export2.

The resulting differential file does not contain the deleted attributes. Sample XML script file snippet export1: 

<client action="update" domain="rel" manufacturer="dilbert" markup="html" markup-version="1.1" 
        name="puppy" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="250" version="1.0">
    <useragent-pattern>dogert</useragent-pattern>
    <client-capability update="set">dish</client-capability>
    <client-capability update="set">html</client-capability>
</client>
Sample XML script file snippet export2: 

<client action="update" domain="rel" manufacturer="dilbert" markup="html" markup-version="1.1" 
        name="" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="287" version="">
    <useragent-pattern>dogert</useragent-pattern>
    <client-capability update="set">dish</client-capability>
    <client-capability update="set">html</client-capability>
</client>
From the two exports above, ReleaseBuilder generates the following differential file: 

<?xml version="1.0" encoding="UTF-8"?>
<!-- IBM WebSphere Portal/6.0 build wp600_154 exported on Wed Apr 05 14:24:19 
    EDT 2006 from xyz -->
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" build="wp600_154" type="update" 
        version="6.0.0.0" xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">
    <portal action="locate">
        <client action="update" objectid="M_CEENUPA000O7002A6CJO0Q1200" ordinal="287"/>
    </portal>
</request>

If you use this ReleaseBuilder differential file to update the 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.

 

Parent topic:

The XML configuration interface