Work with the XML configuration interface

 

+
Search Tips   |   Advanced Search

 

The XML configuration client

You access the XML configuration interface using a command line client contained in...

PORTAL/bin/tools.jar

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

xmlaccess.sh

The basic syntax for the command is as follows: 

   
    xmlaccess -in XML_file 
              -user user 
              -pwd password 
              -url PortalConfigURL 
              -out result.xml

 

Syntax element Description
XML file The name of a file containing the XML request (configuration export or update) that should be processed.

Sample XML_file files can be found in...

wp_root/doc/xml-samples
user and password The 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 The 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 The name of the result file containing the XML output (configuration export). You can later use that file to re-import the exported configuration.

An example for a command line is as follows: 

    xmlaccess -in /home/wpsadmin/export.xml 
              -user wpsadmin 
              -pwd secretpwd 
              -url portal.yourco.com:8082/wps/config

Note: All data, including the user and password, are sent to the server unencrypted. Therefore only connect to the XML configuration interface from inside a protected intranet where you can be sure that the HTTP connection is not compromised.

 

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.2.xsd"
    type="export|update">
       . . . configuration  . . . 
   </request>

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.

 

Transferring a complete configuration

The following example describes a simple case of moving a configuration from one portal to another. More detail is given in the following sections.

Example case: Move a portal configuration from a test portal (named server A) to a production portal (named server B) using the XML configuration interface.

Prerequisites:

To transfer a portal configuration, proceed by the following steps:

  1. Export ServerA configuration using xmlaccess and the provided sample file named Export.xml by entering the following command:

    c:\webshpere\portalserver\bin> xmlaccess.bat -in export.xml -user wpsadmin -pwd wpsadminpwd -url http://ServerA.yourco.com/wps/config -out ServerA_config.xml

    The exported configuration is stored in the XML file ServerA_config.xml .

  2. If you have installed other portlets or applications additional to the ones shipped with the portal, make sure to copy the necessary WAR files from Server A to the installation directory \installableApps\ on Server B.

  3. Use the following command to import the configuration to the ServerB production portal:

    c:\websphere\portalserver\bin> xmlaccess.bat -in ServerA_config.xml -user wpsadmin -pwd wpsadminpwd -url http://ServerB.yourco.com/wps/config

    (This step may take some time.)

    After the request has been processed, make sure that the import process has given the following return message:

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

    The production portal is now ready for use.

 

Exporting and transferring parts of a portal configuration

To export partial configurations 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 wps.SamplePage . Note that this page does not exist in a newly installed portal. You can create it by executing the DeployPortlet.xml sample file.

Normally, you specify the resources that you want to export by their object ID or by their unique name. 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 above results in an XML file similar to ExportPageResult.xml. 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 reimport 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, 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 to export subtrees of the portal content hierarchy. It exports part of the predefined administration page hierarchy that was created during the portal installation.

Finally, the ExportAllPortlets.xml example shows the use of the asterisk character ( * ) as a wildcard 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.

 

Create 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 above, 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, 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 above. 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.

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.

See also