Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows

---

 

Work with the XML configuration interface

 

+

Search Tips   |   Advanced Search

 

1. Overview
2. Terminology
3. Using the XML configuration interface
4. XML configuration through administrative portlets
5. The XML configuration command line client and its syntax
6. Syntax elements of the XML configuration interface
7. XML Syntax for using a secure connection with SSL
8. XML Syntax for exporting and importing credential vault data
9. XML input and output
10. Transfer a complete configuration
11. Staging - transferring a release configuration
12. Exporting and transferring parts of a portal configuration
13. Creating and modifying resources
14. Activating and deactivating portlets, portlet applications, and Web applications
15. Scheduling the delayed cleanup of portal pages
16. Registering predeployed portlets
17. Deregistering users and groups
18. Preparing the deletion of orphaned data

 

Overview

You can use the XML configuration interface to export and import configurations.

XML configuration interface results are influenced by property settings in the configuration services.

Several sample files are available for different purposes of portal configuration using XML. These sample files are documented here for reference purposes only. To use the XML samples for work on the portal configuration, use the files provided in the portal installation, as they might be more up to date than this documentation. The XML sample files are located in...

Linux:	portal_server_root/doc/xml-samples
i5/OS:	portal_server_root/doc/xml-samples
Windows:	portal_server_root\doc\xml-samples

 

Use the XML configuration interface

There are two ways to work with portal configuration data:

• XML configuration command line client
• Administration portlets

The XML configuration command line client provides all the XML configuration interface functions. XML configuration through administrative portlets allows you to export and import configurations.

 

XML configuration through administrative portlets

XML configuration through administrative portlets allows you to export and import configurations. You can export a page or an entire page hierarchy by clicking the Export icon in the Manage pages administration portlet. You 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.

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.

 

The XML configuration command line client

The command line client can be invoked by running...

./xmlaccess.sh|bat

The basic syntax is...

  
   xmlaccess -user user_ID 
             -password password 
             -url myhost:10038/wps/config 
             -in input_file.xml 
             -out result_file.xml

The command line client is contained in the file wp.xml.client.jar in...

Linux:	portal_server_root/bin
i5/OS:	portal_server_root/bin
Windows:	portal_server_root\bin

You also need the file wp.base.jar. It is located in...

Linux:	portal_server_root/shared/app
i5/OS:	portal_server_root/shared/app
Windows:	portal_server_root\shared\app

Connecting to a remote server makes it possible to configure the portal remotely. Copy the three required files to the remote machine and configure the portal from there. All you need is a Java runtime. However, you have to adapt the path settings in the shell scripts accordingly.

All data, including the user ID and password, are sent to the server unencrypted. Use an HTTP connection to connect to the XML configuration interface only from inside a protected intranet where you can be sure that the HTTP connection is not compromised. In all other networks use a secure HTTPS connection to connect to the XML configuration interface.

If you install PK28148 in the portal Version 6.0, you can use the parameter...

askForCredential

...and leave out the parameters user and password. The XML configuration interface will then prompt you for the user ID and password. This can be useful in security sensitive environments, as the user credentials are not visible on the console or in the process view.

   
    xmlaccess -askForCredential 
              -url myhost:9081/wps/config 
              -in input_file.xml 
              -out result_file.xml

For Version 6.0.1 and later, if you leave out the user and password parameters, the XML configuration interface will prompt you for the user credentials.

To access a virtual portal...

  
    xmlaccess -user user_ID 
              -password password 
              -url myhost:10038/wps/config/URL_mapping_context_of_the_VP 
              -in input_file.xml 
              -out result_file.xml

For the URL Mapping context use the mapping that you specified when you created the virtual portal.

 

Syntax elements of the XML configuration interface

Syntax	Description
xmlaccess	The is the shell script. Use one of the following scripts: Linux: ./xmlaccess.sh i5/OS: xmlaccess.sh Windows: xmlaccess.bat
-in	Name of a file containing the XML request (configuration export or update) that should be processed.
-user -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 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.
-askForCredential	If you install PK28148, you can use the parameter askForCredential and leave out the parameters user and password. The XML configuration interface will then prompt you for the user ID and password. The parameter askForCredential requires no value to be specified.
-url	URL to access the configuration servlet. This URL consists of the host name, the base URI as specified during installation (for example /wps), and the servlet extension /config.
-out	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. You 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_ID 
              -password password 
              -url https://myhost:9444/wps/config/ 
              -in input_file.xml 
              -out result_file.xml 
              -truststore trustStore 
              -trustpwd trustPassword 
              -trusttype trustType 
            [ -keystore keyStore 
              -keypwd keyPassword 
              -keytype keyType ]

The https:// prefix in the URL is required. The appropriate HTTPS port must be provided instead of the HTTP port.

The trust* options are mandatory in configurations where a custom certificate store is used, and optional for configurations that use the Java standard cacerts certificate store.

The options starting with the string key are optional.

They are only required when client certificate authentication is used for establishing the SSL connection.

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	Description
-trustStore	Use this element to specify the 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	Use this element to specify the password that is required for accessing the truststore. If the default Java cacerts truststore is used, no trustPassword needs to be provided.
-trustType	Use this element to specify the 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	Use this element to specify the 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	Use this element to specify the password that is required for accessing the keystore. If the default Java cacerts keystore is used, no keyPassword needs to be provided.
-keyType	Use this element to specify the 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.

 

Establish connection using dummy certs

To establish an SSL connection with a WebSphere Portal Express server using the dummy certificate stores provided by 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 $WAS_HOME/profiles/wp_profile/etc/DummyClientTrustFile.jks 
                 -trustPassword WebAS

To run this example configure the SSL configuration in WAS using...

• DummyServerKeyFile.jks
• DummyServerTrustFile.jks

...for secure connections.

This method requires thats that client authentication must not be active.

 

Provide client authentication

If the option require client authentication is active, you need to 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 $WAS_HOME/profiles/wp_profile/etc/DummyClientTrustFile.jks 
                 -trustPassword WebAS 
                 -keyStore $WAS_HOME/profiles/wp_profile/etc/DummyClientKeyFile.jks 
                 -keyPassword 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 WebSphere Portal Express needs to be controlled. Only clients with the correct client certificate will be able establish a connection with WebSphere Portal Express.

 

XML Syntax for exporting and importing credential vault data

When using the XML command line client for credential export, the command syntax is slightly different than normal command line client use because there are two additional parameters:

xmlaccess -user user_ID 
          -password password 
          -url https://myhost:9444/wps/config/ 
          -truststore $WAS_HOME/profiles/wp_profile/etc/DummyClientTrustFile.jks 
          -trustpwd WebAS
          -in input_file.xml 
          -out result_file.xml  
          -credentialexport 
          -passphrase encryptionPassphrase

The following rules apply to the above parameters:

1. The options credentialexport and passphrase are mandatory for export or import of encrypted credential secrets during migration.

2. The options...
   • credentialexport
   • passphrase

   ...are optional for all XML Configuration actions that do not export or import encrypted credential secrets during migration.

 

Additional XML Syntax elements for credential secret migration

Syntax element	Description
-credentialexport	This is a parameter without value that indicates that export of credentials should be enabled
-passphrase	Use this element to specify the encryptionPassPhrase for the encryption. The minimum length of this string is the number of bits set as export keylength in the VaultService.properties file divided by 8. The -passphrase value is used to create a key of the specified length for the encryption.

The following is an example of how to use the XML configuration interface to export/import credential secrets using HTTPS:

    xmlaccess.sh -user wpsadmin 
                 -password your_password 
                 -url https://portalhost:9444/wps/config/ 
                 -in ExportedCredentialSecrets.xml 
                 -out result.xml 
                 -credentialexport 
                 -passphrase JGD786JHgasdf8a67kjhUIT7sdj7nsh776jasdf786regUFZT756675zufurz   
                 -truststore $WAS_HOME/profiles/wp_profile/etc/DummyClientTrustFile.jks 
                 -trustpwd WebAS

Use the same passphrase for both export and import

The import may fail if the user DN schema has been changed between the previous and the current system or when credentials for users are contained in the xml file that are not present in the current system. In this case, manually remove the obsolete credential entries from the XML file before executing the import

For security reasons use an HTTPS connection when importing credentials; however, if you choose not to, set the export.enforceSSL configuration property to false.

 

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 update for the request type.

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. You 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 your operating system and active locale. It may therefore be invalid XML.

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
• update

The normal procedure for exporting a configuration or part of it and then importing it to another consists...

1. Run the XML command line interface with a file that has a request type of export.

   You can use one of the XML sample files.

   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. Modify the XML result file as required.

3. Run the XML command line interface, specifying the XML file that resulted from the XML export.

   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

This example exports the complete portal configuration, not including users, from a stage portal (Server2) to a production portal (prodportal).

Moving users may be useful when transferring configurations between development installations that do not use LDAP for the user repository.

 

Before you begin

• WebSphere Portal Express is installed on stageportal.

• stageportal has the new configuration you want to transfer to prodportal.

• prodportal has an empty portal.

 

To transfer a complete portal configuration:

1. Export stageportal configuration...

   cd portal_server_root/bin

   xmlaccess.sh -in ExportRelease.xml -user wpsadmin -password wpsadminpwd -url http://stageportal.example.com:port/wps/config -out stageportal_config.xml

2. If you have installed other portlets or applications additional to the ones shipped with the portal, copy the necessary WAR files from stageportal to the following directory on prodportal...

   portal_server_root/deployed/archive

On Windows the name of the WAR file must be 25 characters or less.