Working with the XML configuration interface

Terminology

Note the following terminology that is used in the context of the XML configuration interface:

export

This term can have either of the following meanings, depending on the context:

• In the administrative context: a human administrative task, for example exporting a portal configuration or a part of it
• In the context of the XML configuration interface: an XML request and action, for example to export the data of a portal configuration or a part of it.

import

This term represents only the human task in the administrative context, for example importing a portal configuration or a part of it. It has no corresponding request type. In the context of the XML configuration interface, an import is performed by specifying the update request type, together with the create or update action for the resources that are to be imported.

Using the XML configuration interface

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 an XML configuration file by using the Import XML portlet.

The XML configuration command line client and its syntax

You access the XML configuration interface using a command line tool. This command line client is a separate program that connects to the server. Connecting to a remote server makes it possible to configure the portal remotely. The remote connection can be either an HTTP connection, which is not secure, or a secure HTTPS connection. Apply care and use the appropriate type of connection that is required for your environment. 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. For details about how to use an HTTPS connection refer to XML Syntax for using a secure connection with SSL.

Invoke the command line client by using the following shell scripts in the directory wp_profile_root/PortalServer/bin :

• Linux: ./xmlaccess.sh
• IBM i: xmlaccess.sh
• Windows: xmlaccess.bat

The basic syntax for the command is as follows:

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

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

xmlaccess -in Export.xml -useEncryptedCredentials myProperties.properties 
                         -url portal.example.com:10039/wps/config

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

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

Syntax elements of the XML configuration interface

This section lists the syntax elements for using the XML configuration interface over an HTTP connection. For information about the XML syntax elements for a secure HTTPS connection refer to XML Syntax elements for using a secure connection with SSL.

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:10035/wps/config/ 
             -in input_file.xml -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 configurations that 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

xmlaccess.sh -user wpsadmin -password your_password -url https://portalhost:10035/wps/config/
             -in $PortalHome/doc/xml-samples/ExportAllUsers.xml -out result.xml
             -truststore $WASHome/profiles/wp_profile/etc/trust.p12 -trustpwd WebAS -trusttype PKCS12

For this example to run, use the trusttype parameter with a value of PKCS12 to avoid an invalid file format error.

xmlaccess.sh -user wpsadmin -password your_password -url https://portalhost:10035/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, you need to configure the SSL configuration in WebSphere Application Server using the DummyServerKeyFile.jks and the DummyServerTrustFile.jks for secure connections. The option require client authentication must not be active.

xmlaccess.sh -user wpsadmin -password yourpassword -url https://portalhost:10035/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 WebSphere Portal Express needs to be controlled. Only clients with the correct client certificate will be able establish a connection with WebSphere Portal Express.

${JAVA}                                                              
-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www2.protocol           
-classpath ${WPS_HOME}/. . . ..      

XML Syntax for exporting and importing credential vault data

xmlaccess -user user_ID -password password 
   -url https://myhost:10035/wps/config/ 
   -truststore 
    wp_profile_root/config/cells/cellname/nodes/nodename/trust.p12 
   -trusttype PKCS12    -trustpwd WebAS 
   -in input_file.xml -out result_file.xml  
   -credentialexport -passphrase encryptionPassphrase

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

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

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.

Usage - the difference between XML exports and imports

Transferring a complete configuration

To transfer a complete portal configuration, use the WebSphere Portal Express Release Builder. For information about how to use it see the topics about Release Builder.

For information about how to move a complete configuration from a test to a production server refer to Staging - transferring a release configuration.

Staging - transferring a release configuration

If you want to move a complete configuration from a test to a production server by using the portal ReleaseBuilder tool, use the sample file ExportRelease.xml. The attribute domain="rel" indicates that only shared (as opposed to private) resources are exported. This sample file exports the complete portal configuration without private resources as required by the portal ReleaseBuilder tool.

Exporting and transferring parts of a portal configuration

You have already seen an XML request that exports the whole portal configuration. You can also export partial configurations; to do this, you specify the XML hierarchy down to the specific portal resource that you want to export. The element itself has an export action; its parents must be specified with a locate action.

The sample XML request file ExportPage.xml exports a page with the unique name ibm.portal.ssa.SamplePage . Note that this page does not exist in a newly installed portal. You can create it by executing the DeployPortlet.xml sample file, which is covered in the next section.

Normally, you specify the resources that you want to export by their object ID or by their unique name. You can use the Custom Unique Names administration portlet to look up object IDs and unique names of portal resources. Some resources also support lookup by other attributes; see the XML reference documentation for detailed information.

Executing the ExportPage.xml example request file mentioned earlier results in an XML file similar to ExportPageResult.xml. You can use this file 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, in case you delete it later.

When you look at the file, you notice that it includes not only the page itself but also other configuration elements that are referred to by the page, for example the portlet that is placed on the page. These other elements have a locate action. The export does not include their full configuration data, but just enough information to look them up in the portal, assuming they already exist. Note how the configuration of the page makes references to the objectid attributes of other resources, for example in the portletref attribute of the portletinstance elements.

All those references are described by object IDs. Therefore, if the object IDs are correct, the referenced resources could be looked up in the portal even if they were not included in the export. Locating resources before they are referenced is only necessary if you do not know their actual object IDs, so the resources need to be found by some other identifying attribute (see the XML reference documentation). That way, for example a portlet can be identified by its name and by the uid attributes of its parents, and the referencing will still work, even if the object ID is not available for looking up the portlet.

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.

You can import the XML file into another portal to create a copy of the page; of course, this requires that the referenced resources (such as the portlet and the content parents) also exist on the target portal and can be found by an identifying attribute. In that case, 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. You can avoid that by using the ID generating mode (see the XML reference documentation for detail). 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" . . . >  

You can create a duplicate of the page in the portal from where you exported it by using the ID generating mode and changing the unique name of the page in the XML script. This way, the page and its changed name cannot be found for updating by either its object ID or its unique name, therefore a new page with the same settings is created. If you do this, you should change the page title as well, so that you can distinguish between the two pages. The CopyPage.xml sample shows how this script would look.

When exporting resources to XML scripts, it is possible and often useful to export several resources by using one request. The ExportPortletAndPage.xml example extends the ExportPage.xml example by including also the portlet that is contained on the page. The resulting XML file contains the complete configuration data of the portlet and the page.

The ExportSubTree.xml example shows how you export subtrees of the portal content hierarchy. It exports partof the predefined administration page hierarchy that was created during the portal installation.

Using wildcard characters:

Creating and modifying resources

In addition to copying and restoring configurations of existing resources, you can also use the XML configuration interface to install new resources in the portal or as an alternative to the user interface for performing some administration tasks. In these cases, you cannot simply export and re-import XML scripts, but you have to edit them. In most cases, it is still useful to start with an XML export and only partially modify it, rather than writing complete new XML scripts. The following scripts show examples for modifying different resources in the portal configuration by using XML scripts.

Note that all the examples use the ID generating mode and do not specify literal object IDs. Therefore they can be executed on any portal installation and do not depend on hard coded object ID values. As noted earlier, using literal object IDs only makes sense if you really want to create two instances of the same resource, and if you have a controlled environment where you can guarantee that all object IDs that your resources depend on have exactly the required values. As object IDs are difficult to use for identifying the resources, the examples assign unique names to most top-level resources. This way they can be referenced later, and the resources are not duplicated if you execute the scripts twice.

The first example file DeployPortlet.xml shows how you deploy a portlet and create a simple test page to display the portlet. Note that some of the attributes in the XML must match the corresponding settings that were defined in the portlet.xml deployment descriptor in the portlet WAR file. This is necessary so that the XML processing can properly identify the contents of the WAR file. When you want to deploy a different portlet, you must not only specify a different WAR file but also adapt those attributes. Also note that the configuration specified for the portlet is less than what you see in an XML export result for the portlet. For example, the localized titles are not included in the XML script. This is because those settings are specified in the portlet.xml deployment descriptor; there is no need to override them with the XML configuration interface.

The CreatePage.xml sample shows the following additional possibilities:

1. It assumes that the portlet is already installed. Therefore it only uses a locate action for the web module, not an update action.
2. It sets a specific skin for displaying the portlet on the page.
3. It shows how you can specify localized titles in properties files rather than include them in the XML script: the titles and descriptions for the page are now loaded from two properties files for two different languages.

Both examples use a simple page layout with just one row and one column. If you want to generate more complex page layouts, you can use the administration portlets to create them. You can export the result to generate a template for your XML scripts.

When you create new resources, you may want to define specific access control settings for them, for example to make them visible to all portal users. The UpdateAccesscontrol.xml example shows the syntax for specifying different access control settings. This sample updates existing resources, but you can of course use the same syntax to define access control settings for new resources while creating them in an XML script. This sample also shows how you can specify access control user roles on virtual resources. This allows you to give a user access to all resources of a specific type that exist in the portal.

The CreateURL.xml sample defines a URL mapping for the sample page that was created with the DeployPortlet.xml example mentioned earlier. After creating the URL mapping you can access the page directly by entering that URL in the browser.

The DeployTheme.xml example shows how you can use XML scripts to install new themes and skins into your portal. Be aware that the XML scripts create these resources only in the portal database, so that they can be used in the portal. In addition, you have to write the JSPs that perform the actual visualization and copy them to the resource directory specified in the XML before you can use the theme in the portal.

The ModifyPortlet.xml example changes settings of a portlet instance that is shown on a page. Such settings are normally set in the edit mode of the portlet. It depends on the code of the portlet which settings are stored and how they are used.

The CreateUser.xml example imports a new user into the portal. It also creates a group containing only that one user.

To add a new language to the portal, use the CreateLanguage.xml example. Note: To prepare for running this XML script, you have to insert resource bundles and, where applicable, JSPs for the new language. For details about how to do this refer to the topic about how to support new languages in this information center.

The UpdateVault.xml example demonstrates how to create new resources in the portal credential vault with an XML script.

The ClonePortlet.xml example shows how you can use the XML configuration interface to add new portlets with different settings to existing applications.

The Transaction.xml example demonstrates the effect of using different transaction levels for the execution of an XML import.

The MovePage.xml example shows you how to move a page to another node. - Note: 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.

Activating and deactivating portlets, portlet applications, and web applications

You 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 example shows you how to do this.

Scheduling the delayed cleanup of portal pages

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

Registering predeployed portlets

You can manually predeploy portlet application WAR files using the WebSphere Integrated Solutions Console. You can later register and configure the predeployed portlet applications into WebSphere Portal Express, together with other J2EE resources and artifacts, by using the XML configuration interface. Use the sample file RegisterPreDeployedEAR.xml to install a predeployed portlet. You might have to change this sample for your requirements. For more information about how to predeploy portlets refer to the topic about predeployed portlets in this information center.

Deregistering users and groups

If portal users or groups have been removed from the user registry, but not from the portal database, or if users have had their user ID deactivated, for example after too many wrong password attempts, you 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.

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