XML configuration interface

 

+
Search Tips   |   Advanced Search

 

Contents

  1. XML configuration portlets
  2. XML configuration command line client
  3. Transfer a complete configuration
  4. Export parts of a portal configuration
  5. Create resources
  6. Activate portlets, portlet applications, and Web applications
  7. Scheduling the delayed cleanup of portal pages
  8. Register predeployed portlets
  9. Deregistering users and groups from the portal

 

XML configuration portlets

The XML configuration interfaces allows one to export and import pages.

To export a page or page hierarchy using the Manage pages portlet, click the export button for a specific page.

When the export is complete you see a success message. If the export fails, you will see a <failure> tag.

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.

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

 

XML configuration command line client

You access the XML configuration interface using a command line tool. This command line client is a separate program that connects to the server using an HTTP connection. This also makes it possible to configure the portal remotely.

The command line client is contained in...

wp_root/bin/wp.xml.client.jar

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

xmlaccess.sh

You can copy these three files to a separate 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.

The basic syntax for the command is as follows: 

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

If you have virtual portals in your portal configuration, you can access them using... 

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

The sequence of the options is of no significance.

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. You can later use this file to re-import the exported configuration.

An example for a command line is as follows: 

xmlaccess -in /home/wpsadmin/export.xml  \
          -user wpsadmin  \
          -password secretpwd  \
          -url portal.setgetweb.com:9081/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.3.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. 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

Note the following hints for working with the XML configuration interface:

  • 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, you 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. This step is 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. You 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

The following example describes a simple case of moving a configuration from one portal to another.

This example exports the complete portal configuration (not including users). Exporting users is not desirable when you transfer configurations between different portal installations because the systems should be configured to use the same user repository. Transferring users may be useful when transferring configurations between development installations.

To move a a portal configuration from Server A to Server B...

  1. Configure Portal on Server B as an empty portal

  2. Configure both servers to use the same LDAP directory, LDAP base DN, and so on.

  3. Export the entire portal configuration (not including users) on Server A....

    1. On Server A, cd to...
      wp_root/bin

      This directory contains the WebSphere Portal tools.

    2. Export the Server A configuration using the provided sample file... 

      ./xmlaccess.sh -in ExportRelease.xml \
               -user wpsadmin \
               -password wpsadminpwd \
               -url http://ServerA.setgetweb.com/wps/config \
               -out ServerA_config.xml

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

    3. 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 following directory on Server B:

      wp_root/installableApps

      Note: As Windows limits the maximum path length to 260 characters, the name of the WAR file must be 25 characters or less. Installing a WAR file with a name that is more than 25 characters will result in an error.

  4. Verify that all URLs in the XML file ServerA_config.xml that resulted from the export are valid. This means that all the files that are listed in the XML result file must be present and accessible in the specified locations on Server B. If files are listed in the XML script, but not available under the specified location, proceed as follows:

    • For WAR files:

      Either update the URLs specified in the XML script file ServerA_config.xml according to the actual location of the files, or copy the files to the locations specified in the XML script.

    • For predeployed portlet files:

      Update the URLs specified in the XML file ServerA_config.xml according to the actual location of the file. For example, for the Personalization portlets that are predeployed as part of the portal installation, open the file ServerA_config.xml in a text editor and search for the following URLs:

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

      Replace them with the following URLs:

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

  5. Import the entire portal configuration (not including users) on Server B. To do this, proceed by the following steps:

    1. On Server B change to the following directory:

      wp_root/bin
      This directory contains the WebSphere Portal tools.

    2. Use the following command to import the configuration to the Server B production portal: 

      ./xmlaccess.sh -in ServerA_config.xml \
               -user wpsadmin \
               -password wpsadminpwd \
               -url http://ServerB.setgetweb.com/wps/config

      (This step may take some time.)

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

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

      The production portal is now ready for use.

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 export-release="true" 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. For more information about using the ReleaseBuilder refer to About ReleaseBuilder.

 

Export 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 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, 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. 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 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, 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 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 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.

Note: As Windows limits the maximum path length to 260 characters, the name of the WAR file must be 25 characters or less. Deploying a WAR file with a name that is more than 25 characters will result in an error.

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.

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.

 

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

For details about the portal resource cleanup service, refer to Delayed cleanup of deleted portal pages.

For more details about how to configure the schedule for the delayed deletion cleanup or run an individual cleanup, refer to the XML reference under the task tag.

Note: 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 application error when browsing that re-created page. For more details about this refer to Re-creating and browsing a page can result in an application error.

 

Register predeployed portlets

You can manually predeploy portlet application WAR files using the WebSphere Application Server Administration console. You 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. 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 Deploying J2EE resources with portlet application WAR files.

 

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 been muted, 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.

The CleanupUsers.xml sample file shows an example of how you can export such users and groups. The resulting output file lists the affected users and groups with their action set to delete. You need to check the list and remove all users and groups that you want to keep in the portal database. For example, you might want to keep the muted users and re-enable their passwords. After you have done this, import the file into your portal. All users and groups that remain in the list are removed from the portal database.

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

For more details about deregistering users and groups refer to Deregistering Users and Groups from WebSphere Portal.

 

See also

Library | Support | Terms of use | Feedback

Information Center last updated: Wednesday, June 1, 2005

IBM WebSphere Portal for Multiplatforms V5.1.x | (c) Copyright IBM Corporation 2000, 2005

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.