XML configuration interface

 

+
Search Tips   |   Advanced Search

 

  1. Overview
  2. The XML configuration command line client
  3. Transfer a complete configuration
  4. Stage - transferring a release configuration
  5. Export parts of a portal configuration
  6. Create and modify resources
  7. XML configuration through administrative portlets
  8. Activate portlets, portlet applications, and Web applications
  9. Schedule the delayed cleanup of portal pages
  10. Register predeployed portlets
  11. Deregister users and groups
  12. Prepare the deletion of orphaned data

 

Overview

Use the XML configuration interface to configure the portal's framework of services.

We can access the XML configuration interface via...

command line client Provides all the XML configuration interface functions
administration portlets Export and import configurations.

 

XML configuration command line client

The syntax for the XML configuration command line client is... 

 
xmlaccess -user user   
          -password password   
          -url myhost:10038/wps/config   
          -in XML_file   
          -out result.xml

Sample XML_file files are located in...

portal_server_root/doc/xml-samples

Virtual portals can be accessed using... 

xmlaccess -user user 
          -password password 
          -url myhost:10038/wps/config/URL_mapping_context_of_the_VP 
          -in  XML_file 
          -out result.xml

To use xmlaccess, the following files are required....

portal_server_root/bin/wp.xml.client.jar
portal_server_root/shared/app/wp.base.jar

To run xmlaccess on a remote machine, copy required files to the remote machine. All we need is a Java runtime. Adapt the path settings in the shell scripts accordingly.

The sequence of the options is of no significance.

An example for a command line is as follows: 

    xmlaccess -in /home/wpsadmin/export.xml 
              -user wpsadmin 
              -password secretpwd 
              -url portal.setgetweb.com:10038/wps/config

All data, including the user and password, are sent to the server unencrypted.

 

Syntax elements of the XML configuration interface

This section lists the syntax elements for using the XML configuration interface over an HTTP connection.

Syntax element Description
xmlaccess Shell script: ./xmlaccess.sh
XML file Name of a file containing the XML request (configuration export or update) that should be processed.
user and password User identification and password describing the authority under which the request should be processed.

For the value for user specify the short username as specified during portal login; full distinguished names (DN) are not supported. The XML configuration interface is only accessible to users that have the manager role on the virtual resource XML_ACCESS and the administrator role on the virtual resource PORTAL.

PortalConfigURL URL to access the portal configuration servlet.

This URL consists of the portal host.name, the base URI for the portal as specified during installation (for example /wps), and the servlet extension /config.

result.xml Name of the result file that contains the XML output.

This file gives a result status and thereby indicates whether the XML request was performed successfully, or what errors might have occurred. In the case of an XML export, this file contains the exported configuration. We can later use this file to re-import the exported configuration.

 

XML Syntax for using a secure connection with SSL

When you use the XML command line client with SSL over a secure HTTPS connection, the command syntax is as follows: 

   
    xmlaccess -user user 
              -password password 
              -url https://myhost:9444/wps/config/ 
              -in XML_file 
              -out result_file.xml  
              -truststore trustStore 
              -trustpwd trustPassword 
              -trusttype trustType [ -keystore keyStore 
                                     -keypwd keyPassword 
                                     -keytype keyType ]

The following rules apply:

  1. The https:// prefix in the URL is required to allow the XML client to detect whether a secure HTTPS connection is required. The appropriate HTTPS port must be provided instead of the HTTP port.

  2. The options starting with the string trust are mandatory in all configurations where a custom certificate store is used for storing certificates required for secure connections. For setups which use the java standard cacerts certificate store, the parameters starting with trust are optional.

  3. The options starting with the string key are optional. They are only required when client certificate authentication is used for establishing the SSL connection.

  4. The default value for keytype and trusttype is jks. Therefore the keytype and trusttype options are optional unless the used keystore or truststore uses a different format.

 

XML Syntax elements for using a secure connection with SSL

Syntax element Description
trustStore Name of the truststore file that contains the server certificates that are required for accepting SSL connections with trusted servers.

If no truststore is provided, the XML client will use the default Java cacerts truststore.

trustPassword Password that is required for accessing the truststore.

If the default Java cacerts truststore is used, no trustPassword needs to be provided.

trustType Type of the truststore that is used.

The default type is jks. As long as the used truststore is of type jks, you do not have to provide this parameter.

keyStore Name of the keystore file that contains client certificates that are required for establishing an SSL connection with a server that requires client certificate authentication.

If no keystore is provided, the XML client will use the default Java cacerts keystore.

keyPassword Password that is required for accessing the keystore.

If the default Java cacerts keystore is used, no keyPassword needs to be provided.

keyType Type of the used keystore.

The default type is jks. If the used keystore is of type jks, you do not have to provide this parameter.

Examples:

  1. The following is an example of how to use the XML configuration interface to establish an SSL connection with a WebSphere Portal server, using the dummy certificate stores that are provided by WebSphere Application Server (WAS) : 

        xmlaccess.sh -user wpsadmin 
                 -password your_password 
                 -url https://portalhost:9444/wps/config/ 
                 -in $PortalHome/doc/xml-samples/ExportAllUsers.xml 
                 -out result.xml 
                 -truststore $WASHome/profiles/wp_profile/etc/DummyClientTrustFile.jks 
                 -trustpwd WebAS

    For this example to be able to run, configure the SSL configuration in WAS using the DummyServerKeyFile.jks and the DummyServerTrustFile.jks for secure connections. The option require client authentication must not be active.

  2. If the option require client authentication is active, provide a keyfile when establishing the SSL connection with the XML configuration interface: 

       
    xmlaccess.sh -user wpsadmin -password yourpassword 
                 -url https://portalhost:9444/wps/config/ 
                 -in $PortalHome/doc/xml-samples/ExportAllUsers.xml 
                 -out result.xml 
                 -truststore $WASHome/profiles/wp_profile/etc/DummyClientTrustFile.jks 
                 -trustpwd WebAS 
                 -keystore $WASHome/profiles/wp_profile/etc/DummyClientKeyFile.jks 
                 -keypwd WebAS

    This example allows the XML configuration interface to send a client certificate to the server, if the server requests one. Using client certificate authentication is required wherever the number of clients that can administer the Portal needs to be controlled. Only clients with the correct client certificate will be able establish a connection with the Portal.

 

XML input and output

An XML file that you process must always be in UTF-8 encoding and must specify the following root element and schema: 

   <?xml version="1.0" encoding="UTF-8"?>

   <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"
            type="export|update">

          ... configuration ... 

   </request>

For an XML export, specify export for the request type. For an XML import, specify a request type of update. The line where you specify either of these request types is highlighted in the example above.

When the XML request has been processed on the server, the resulting XML output is sent back to the client and written to the standard output. We can write the output to an XML file by using the -out command line option. Using this option always writes the output in UTF-8 encoding. If you do not use this option, the output is written in a console encoding that depends on the operating system and active locale. It may therefore be invalid XML.

 

The difference between XML exports and imports

The command line syntax and XML processing is the same for both exports and imports. You specify an XML input file to the XML configuration interface, and the XML configuration interface returns a resulting XML file.

The difference between export and import is determined by whether you set the request type to export or update in the XML file that you specify in the command line request. When importing, the resources action attribute can have the following values: locate, create or update.

The normal procedure for exporting a configuration or part of it and then importing it to another portal consists of the following steps:

  1. Run the XML command line interface with a file that has a request type of export in it. For example, we can use one of the XML sample files with request type export supplied with WebSphere Portal.

    The XML command line interface returns a result file that contains the portal resources specified in the XML file that you used for the export. This can be, for example a portal resource and all dependent resources. The file returned by the XML command line interface has specified update for the request type and locate or update for the individual resources actions. This file is ready to be used for an XML import.

  2. (Optional) Modify the XML result file from the export as required, for example to create additional resources using create or update.

  3. Run the XML command line interface, specifying the XML file that resulted from the XML export and that you might have modified. We can also use one of the XML sample files with request type update in it. The XML command line interface returns a result file that indicates whether the specified resources were imported successfully, or what errors might have occurred.

 

Transfer a complete configuration

In this example you use xmlaccess to transfer a complete portal configuration, excluding users, from TestServer to ProdServer.

Exporting users is not required because TestServer and ProdServer are configured to use the same user repository.

WebSphere Portal on ProdServer has been installed as an empty portal.

  • No portlets have been installed.
  • No pages have been created.

Procedure...

  1. On TestServer

    1. Export the entire portal configuration (not including users)... 
      cd portal_server_root/bin 

      
./xmlaccess.sh -in ../doc/xml-samples/ExportRelease.xml \
               -user wpsadmin   \
               -password wpsadminpwd \
               -url http://TestServer.setgetweb.com/wps/config \
               -out /tmp/TestServer_config.xml

    2. Copy custom portlet *.war files to...

  2. Verify URLs in TestServer_config.xml are valid.

    All files referenced must be accessible in the specified locations on ProdServer. In general, all deployed WAR files are copied to the directory...

    portal_server_root/installableApps/deployed/archive

    Therefore it may be sufficient to copy the contents of...

    ...to the corresponding directory on the target server and leave TestServer_config.xml unchanged. However, to be sure, check the file for warnings related to wrong URLs. If files are listed in the XML script, but not available under the specified location...

    For WAR files, update the URLs specified in TestServer_config.xml to point to actual location or copy the *.war files to the locations specified.

    For predeployed portlet files update the URLs according to the actual location of the file. For example, for the Personalization portlets that are predeployed as part of the portal installation, edit TestServer_config.xml and replace... 

    <url>file://localhost/$server_root$/installableApps/pznauthorportlet.war</url>
<url>file://localhost/$server_root$/installableApps/pznruleportlet.war</url>

    ...with... 

    <url>file://localhost/$server_root$/installedApps/Personalization Workspace 6.ear/pznauthorportlet.war</url>
<url>file://localhost/$server_root$/installedApps/Personalization Lists 6.ear/pznruleportlet.war</url>

  3. For policy files that are referenced by a <policy-node>, copy the files to the correct file locations on ProdServer, or update the URLs in the XML script to the correct locations.

    Use policies to specify and apply common and specialized settings that determine the how portal resources function for different classes of users. When you use the XML configuration interface to work with policies, some limitations apply.

  4. On ProdServer, import the entire portal configuration (not including users)... 

    cd portal_server_root/bin 
./xmlaccess.sh -in TestServer_config.xml                           \
               -user wpsadmin                                      \
               -password wpsadminpwd                               \
               -url http://ProdServer.setgetweb.com/wps/config

    (Allow some time for this step to complete.)

    After the request has been processed, verify the import process has given the following return message: 

     <status element="all" result="ok">

  5. If the transfer included the Document Manager...

    1. Log in to the WAS 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 changes and restart the portal.

The production portal is now ready for use.

 

Transfer a release configuration

ExportRelease.xml will export the complete portal configuration without private resources as required by the portal ReleaseBuilder tool.

The attribute...

domain="rel"

...indicates that only shared (as opposed to private) resources are exported.

 

Export parts of a portal configuration

ExportPage.xml Export page with the unique name...

ibm.portal.SamplePage

This page does not exist in a newly installed portal. We can create it by executing DeployPortlet.xml.

Specify the resources to export using...

Use the Custom Unique Names portlet to look up object IDs and unique names.

Executing ExportPage.xml results in an XML file, ExportPageResult.xml, which can be used to update the page to the exported state, if it still exists in the portal. You could also use this file to re-create the page, if it is ever deleted.

The file also includes configuration elements referred to by the page, for example portlets placed on the page, using a locate action.

The configuration references resource objectids. In, for example, the portletref attribute of portletinstance elements.

References are described by object IDs can be used to look up resources even if they are not included in the export.

Exporting resource configurations normally creates update actions for all exported elements. This means that if the portal resource already exists on the importing system, the settings are modified, and if it does not yet exist, it is created. This in turn means that if you re-import the page into the portal that you exported it from, nothing changes.

We can import the XML file into another portal to create a copy of the page. Referenced resources, such as the portlet and the content parents, must exist on the target portal. The page and all contained resources take their object IDs with them, so that they have the same object IDs on the source and target system - the resources retain their identity. We can avoid that by using the ID generating mode. When you use the ID generating mode, the object IDs in the input are not taken literally, but during the import process the resources obtain new object IDs when they are created on the target system.

You apply ID generating mode by adding the following attribute to the main request tag: 

   <request... create-oids="true"... >
CopyPage.xml Create duplicates of the page in the portal from where it was exported, by exporting the page using the ID generating mode, and then changing the unique name of the page in the XML script. Change the page title to distinguish between the two pages.
ExportPortletAndPage.xml Extends ExportPage.xml, exporting an XML file that contains the complete configuration data of the portlet and the page.
ExportSubTree.xml Export subtrees of the portal content hierarchy created during the portal installation.
ExportAllPortlets.xml Use the asterisk character (*) to export all resources of a given type. This example exports all the Web modules that have been installed in the portal and their contained portlets.

 

Install new resources

DeployPortlet.xml Deploy a portlet and create a simple test page to display the portlet.
CreatePage.xml Assumes that the portlet is already installed, using a locate action for the Web module, not an update action.

Sets a specific skin for displaying the portlet on the page.

Specify localized titles in properties files rather than including them in the XML script.

UpdateAccesscontrol.xml Set different access control settings and specify user roles on virtual resources, giving a user access to all resources of a specific type.
CreateURL.xml Define a URL mapping for the sample page created with DeployPortlet.xml.
DeployTheme.xml Install new themes and skins in the portal database. JSPs files associated with the themes and skins need to be manually copied to the specified resource directory.
ModifyPortlet.xml Change settings of a portlet instance. Such settings are normally set in the edit mode of the portlet.
CreateUser.xml Import a new user into the portal. Create a group containing only that one user.
CreateLanguage.xml. Add a new language to the portal.

Before running, insert resource bundles and, where applicable, JSPs for the new language.

UpdateVault.xml Create new resources in the credential vault.
ClonePortlet.xml Add new portlets with different settings to existing applications.
Transaction.xml Use different transaction levels for the execution of an XML import.
MovePage.xml Move a page to another node.

The actual move of the page is done by the last two lines in the sample file. They are highlighted in the representation of the sample file here.

 

XML configuration through administrative portlets

XML configuration through administrative portlets allows you to export and import configurations. We can export a page or an entire page hierarchy by clicking the Export icon in the Manage pages administration portlet. We can also import any XML configuration file using the Import XML portlet.

To export a page or an entire page hierarchy using the Manage pages portlet:

  1. On the Manage Pages portlet, click the export button for a specific page.

  2. You are then asked if you want to export the entire page hierarchy or only the selected page. Proceed as follows.

    • Click Yes to export the entire page hierarchy.

    • Click No to only export the selected page.

    • Click Cancel to stop the page export.

  3. If you selected Yes or No you are prompted to save the configuration file. Provide a file name and select the location where you want it saved.

  4. When the export is complete you see a success message.

  5. Check the content of the saved XML configuration file to make sure that a <failure> tag does not exist. On the Download complete screen, click Open to view the newly saved XML file. If you do not want to view the XML file, close the extra window that is open for viewing the file.

We can import an XML configuration file by using the XML Import portlet.

To import an XML configuration file using the Import XML portlet:

  1. On the Import XML portlet, locate the xml configuration file that you want to import. Use the browse button to help locate the file.

  2. Click Import to import the configuration.

  3. When the import is complete you see a success message.

 

Activating and deactivating portlets, portlet applications, and Web applications

We can change the states of portlets, portlet applications, and Web applications between active and inactive by using the portal XML configuration interface. The ActivatePortlet.xml shows you how to do this.

 

Scheduling the delayed cleanup of portal pages

Task.xml shows you how to schedule the cleanup of pages that have been marked for deletion.

If you delete a page with an object ID and then 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.

 

Registering predeployed portlets

We can manually predeploy portlet application WAR files using the WAS Administration console. We can later register and configure the predeployed portlet applications into WebSphere Portal, together with other J2EE resources and artifacts, by using the XML configuration interface.

Tweak the sample file...

RegisterPreDeployedEAR.xml

...to install a predeployed portlet.

 

Deregister users and groups

CleanupUsers.xml exports users and groups that have been removed from the user registry, but not from the portal database.

The output file lists the affected users and groups with their action set to delete.

If users have been muted, for example after too many wrong password attempts, we can identify and list these users and groups by using the cleanup-users attribute. Specify the cleanup-users attribute with the request tag of type export, and set its value to true. You also need to set the export-users attribute to true.

Remove users and groups that you want to keep. For example, keep muted users and re-enable their passwords. After you have done this, import the file into the portal. All users and groups that remain in the list are removed from the portal database.

After deleting these entries via the modified XML script, all customization is lost for the deleted users and groups.

 

Prepare the deletion of orphaned data

To prepare for deleting orphaned data, use the ExportIncludingOrphanedData.xml example to perform an export that includes all orphaned data.

 

Related information

 

Parent topic:

The XML configuration interface