Work with the xmlaccess

 

+

Search Tips   |   Advanced Search

 

Use the XML Configuration Interface (xmlaccess) to export and import configurations.

The XML sample files are located in...

 

XML configuration through administrative portlets

You can export a page or an entire page hierarchy by clicking the Export icon in the Manage Pages portlet.

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

 

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 interface: xmlaccess

To invoke...

The basic syntax for the command... 

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

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

You can use the parameter askForCredential and leave out the parameters user and password. The xmlaccess 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

If you leave out the user and password parameters, the xmlaccess will prompt you for the user credentials.

Note that there is a security vulnerability in XML Access versions 6.0.0.1 through 6.0.1.3. This vulnerability is fixed in WebSphere Portal 6.0.1 Fix Pack 4 (6.0.1.4)

If you have virtual portals in your configuration, you can access the virtual portals as follows: 

     
xmlaccess -user user_ID 
          -password password 
          -url myhost:10040/Virtual_Portal_URL 
          -in input_file.xml 
          -out result_file.xml

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

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

To use xmlaccess remotely copy the three required files (depending on your operating system) to the remote machine and configure your portal from there. All that is required on the remote machine is a Java runtime.

 

Syntax elements of the xmlaccess

Syntax element Description
-in Name of a file containing the XML request to be processed.
-user -password User identification and password describing the authority under which the request should be processed.

Specify the short username as specified during login. Full distinguished names are not supported.

xmlaccess is only accessible to users that have...

-askForCredential If user/password not specified, and this parameter is used, the xmlaccess 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, /wps, and the servlet extension, /config.

-out The 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.

 

Use a secure connection with SSL

When you use the XML command line client with SSL over a secure HTTPS connection, the command syntax... 

   
xmlaccess -user user_ID 
          -password password 
          -url https://myhost:9444/w 
          -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 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.

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.

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.

 

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

 

Example 1:

The following is an example of how to use the xmlaccess to establish an SSL connection with a WebSphere Portal server, using the dummy certificate stores that are provided by WAS: 

 xmlaccess.sh -user wpsadmin 
             -password your_password 
             -url https://portalhost:9444/w 
             -in $PortalHome/doc/xml-samples/ExportAllUsers.xml 
             -out result.xml 
             -trustStore $WASHome/profiles/wp_profile/etc/DummyClientTrustFile.jks 
             -trustPassword 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.

 

Example 2:

If the option require client authentication is active, provide a keyfile when establishing the SSL connection with the xmlaccess: 

 xmlaccess.sh -user wpsadmin 
             -password yourpassword 
             -url https://portalhost:9444/w 
             -in $PortalHome/doc/xml-samples/ExportAllUsers.xml 
             -out result.xml 
             -trustStore $WASHome/profiles/wp_profile/etc/DummyClientTrustFile.jks 
             -trustPassword WebAS 
             -keyStore $WASHome/profiles/wp_profile/etc/DummyClientKeyFile.jks 
             -keyPassword WebAS

This example allows the xmlaccess 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 needs to be controlled. Only clients with the correct client certificate will be able establish a connection with WebSphere Portal.

 

Export and import 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/w 
          -truststore WP_PROFILEnode/trust.p12 
          -trusttype PKCS12 
          -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 and passphrase are optional for all XML Configuration actions that do not export or import encrypted credential secrets during migration.

Before running the xmlaccess command, ensure that you have added the following properties to the WAS configuration.

  1. Log in to the WAS administrative console, and click...

    Resources | Resource Environment | Resource Environment | Providers | WP_VaultService | Custom properties

  2. Add the property export.userDN.

    • Name: export.userDN
    • Value: administrator_DN. For example: cn=wpsadmin,o=ibm
    • Type: java.lang.String

  3. Add the property export.enforceSSL.

    • Name: export.enforceSSL
    • Value: true
    • Type: java.lang.Boolean

  4. Save your configuration changes and restart the portal server.

 

Additional elements for credential secret migration

Syntax element Description
-credentialexport Parameter without value that indicates that export of credentials should be enabled
-passphrase 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/w 
             -in ExportedCredentialSecrets.xml 
             -out result.xml 
             -credentialexport 
             -passphrase JGD786JHgasdf8a67kjhUIT7sdj7nsh776jasdf786regUFZT756675zufurz
             -truststore $WASHome/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

Use an HTTPS connection when importing credentials. If you choose not to, set...

export.enforceSSL = 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 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.

 

XML exports and imports

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

For exports set the request type to...

...in the XML file specified in the command line request.

For imports, set the resources action attribute to...

The normal procedure for exporting a configuration or part of it and then importing it to another 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, 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 resources specified in the XML file that you used for the export. This can be, for example a 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. 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 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.

Example case: Move a configuration from ServerA to ServerB using the xmlaccess.

 

Before you begin, ensure all of the following:

 

To transfer a complete portal configuration:

  1. To export the entire portal configuration (not including users) on ServerA:

    1. On ServerA change to the following directory:

        WP_PROFILE\PortalServer\bin

    2. Export ServerA configuration... 

      ./xmlaccess.sh -in ExportRelease.xml 
               -user wpsadmin         
               -password wpsadminpwd 
               -url http://ServerA.example.com:port/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 in addition to the ones shipped with the portal, make sure to copy the necessary WAR files from ServerA to the following directory on ServerB:

      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.

  2. Verify that all URLs in the 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 ServerB. In general, all deployed WAR files are copied to...

    portal_server_root/deployed/archive

    Therefore it may be sufficient to copy the contents of that deployed/archive directory to the corresponding directory on your target server and leave the file ServerA_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: 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//opt/IBM/WebSphere/$server_root$/installedApps/Personalization Workspace 6.ear/pznauthorportlet.war</url>

    • <url>file://localhost//opt/IBM/WebSphere/$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 ServerB, or update the URLs in the XML script to the correct locations. For more information about policies refer to the appropriate section in this information center.

    When you use the xmlaccess to work with policies, some limitations apply.

  4. If this is a clustered environment, modify the xml file to remove the global-settings and services-settings entries if available in the file.

  5. To import the entire portal configuration (not including users) on ServerB:

    1. On ServerB change to the following directory:

        WP_PROFILE/PortalServer/bin

    2. Import the configuration to ServerB:

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

      (Allow some time for this step to complete.)

    3. If this is a clustered environment:

      1. Resync the cluster from the Deployment Manager console.

      2. Restart the Enterprise Applications from the Deployment Manager console.

      3. Activate the deployed portlets:

          ./ConfigEngine.sh activate-portlets

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

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

  6. Restart the portal.

The production portal is now ready for use.

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 can export partial configurations by specifying 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 ExportPage.xml exports a page with the unique name wps.SamplePage. Note that wps.SamplePage does not exist in a newly installed portal. You can create it by executing DeployPortlet.xml.

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.

Executing ExportPage.xml results in an XML file similar to ExportPageResult.xml, which can be used to...

The file 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.

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.

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 ID generating mode.

When you use 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 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. ExportPortletAndPage.xml extends ExportPage.xml 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.

ExportSubTree.xml 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.

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.

 

Creating and modifying resources

In addition to copying and restoring configurations of existing resources, you use the xmlaccess 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 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.

DeployPortlet.xml Shows how you deploy a portlet and create a simple test page to display the portlet.

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

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.

CreatePage.xml 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. To generate more complex page layouts, 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.

UpdateAccesscontrol.xml Shows 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 one to give a user access to all resources of a specific type that exist in the portal.
CreateURL.xml Define a URL mapping for the sample page that was created with DeployPortlet.xml. After creating the URL mapping you can access the page directly by entering that URL in the browser.
DeployTheme.xml 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 use the theme in the portal.
ModifyPortlet.xml Change 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.
CreateUser.xml Import a new user into the portal. It also creates a group containing only that one user.
CreateLanguage.xml Add a new language to the portal.

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.

UpdateVault.xml Create new resources in the portal credential vault with an XML script.
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.

 

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

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. Notes:

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

  2. When you run the cleanup task, the xmlaccess only schedules the task to be run in WAS and returns. This does not necessarily mean that WAS runs the task immediately. To determine when a task started and ended, check the portal log SystemOut.log for the EJPDE0002I and JPDE0003I messages. These messages confirm that the cleanup task has successfully completed. After you have confirmed this, you can run the XML script for re-creating a page with the same object ID as it had before the deletion.

 

Registering predeployed portlets

You can manually predeploy portlet application WAR files using the WAS 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 xmlaccess. Use the sample file RegisterPreDeployedEAR.xml to install a predeployed portlet. You might have to change this sample for your requirements.

 

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.

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

 

Preparing the deletion of orphaned data

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

 

Parent topic

The xmlaccess