Work with the XML Configuration


  1. Overview
  2. Configuration through administrative portlets
  3. Configuration through xmlaccess
    1. Encrypt xmlaccess traffic
    2. Use xmlaccess from machine w/o portal installed
  4. Virtual portals
  5. Syntax elements of xmlaccess.sh
  6. Secure connection with SSL
    1. Using WAS default certificate stores
    2. Use WAS dummy certificate stores
    3. Key file for client authentication
  7. Export and import credential vault data
  8. XML input and output
    1. The difference between XML exports and imports
  9. Transfer a complete configuration
  10. Export and transfer parts of a portal configuration
  11. Create and modify resources
  12. Activate and deactivate portlets, portlet applications, and web applications
  13. Schedule the delayed cleanup of portal pages
  14. Register predeployed portlets
  15. Deregister users and groups
  16. Prepare the deletion of orphaned data


Overview

Use xmlaccess.sh to export and import configurations.

XML sample files are located in...

ActivatePortlet.xml DeleteFilter.xml ExportStaticPage.xml
CleanSystemSlots.xml DeletePage.xml ExportSubTree.xml
CleanupUsers.xml DeletePortlet.xml ExportTagsAndRatings.xml
ClonePortlet.xml DeleteTagsAndRatings.xml ExportTasks.xml
CopyPage.xml DeleteUser.xml ExportUserResource.xml
CreateApplicationFolder.xml DeployPortlet.xml ExportWSRPCustomizedPortletInstances.xml
CreateCsaPage.xml DeployTheme.xml ExportWSRPProducer.xml
CreateFilter.xml DeployThemeFromWebModule.xml ExportWSRPProducersAndPortlets.xml
CreateLanguage.xml Export.xml IntegrateRemotePortlet.xml
CreateLegacyPage.xml ExportAllPolicyNodes.xml ModifyPortlet.xml
CreatePage.xml ExportAllPortlets.xml MovePage.xml
CreatePageFromTemplate.xml ExportAllUsers.xml RegisterPreDeployedEAR.xml
CreatePageFromZip.xml ExportIncludingOrphanedData.xml Task.xml
CreateTagsAndRatings.xml ExportPage.xml Transaction.xml
CreateTemplateFolder.xml ExportPageResult.xml UpdateAccesscontrol.xml
CreateUrl.xml ExportPortletAndPage.xml UpdateFilter.xml
CreateUser.xml ExportPortletAndStaticPage.xml UpdatePortlet.xml
CreateWSRPProducer.xml ExportRelease.xml UpdateVault.xml

There are two ways to work with portal configuration data:


XML configuration through administrative portlets

Export a page or page hierarchy by clicking...

Administration | Portal User Interface | Manage pages | Export icon

After exporting, check the content of the saved XML configuration file to verify a <failure> tag does not exist.

Import XML configuration using...

Administration | Portal Settings | Import XML

In browser, enable support for JavaScript and disable pop-up blocking.


XML configuration through xmlaccess

The xmlaccess.sh command line client connects to the server through http/https, making it possible to configure the portal remotely.


Encrypt xmlaccess traffic

All data, including the user ID and password, are sent to the server unencrypted. Therefore you should only connect to xmlaccess.sh 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 xmlaccess.sh.

If you use the parameter -askForCredential, and leave out the parameters user and password, xmlaccess will 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.

You can also place the credentials in a properties file and use the option -useEncryptedCredentials This option reads the encrypted or unencrypted credentials from the properties file, and then saves the file back using the encrypted password. Use -PropFilePasswordEncoder to encrypt the password in the properties file. This option reads the following properties out of the file:

An example of a command line is as follows

If you do not want to write the properties file back with the encrypted credentials, use the additional flag -noUpdateProperties.


Use xmlaccess from machine w/o portal installed

To use from a machine that does not have portal installed, copy the four files below to the machine and configure the portal from there. The machine should have a Java run time.

$PORTAL_HOME/base/wp.xml.client/bin/wp.xml.client.jar
$PORTAL_HOME/base/wp.base/shared/app/wp.base.jar
WAS_HOME/lib/j2ee.jar
$PORTAL_HOME/bin/xmlaccess.sh

Adapt the path settings in the shell scripts accordingly.

When you update portal by installing fix packs, these files might be updated. Always use the most recent versions of these files.


Virtual portals

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


Syntax elements of xmlaccess.sh

Syntax element Description
xmlaccess.sh Found in $PORTAL_HOME/bin
-in 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 user name as specified during login; full distinguished names (DN) are not supported. xmlaccess.sh is only accessible to users that have the manager role on the virtual resource XML_ACCESS and the administrator role on the virtual resource PORTAL.
-askForCredential You can use the parameter askForCredential and leave out the parameters user and password. xmlaccess.sh will then prompt you for the user ID and password. The parameter askForCredential requires no value to be specified.
-useEncryptedCredentials User credentials in a properties file rather than with the XML command.
-noUpdateProperties Use additionally with the option useEncryptedCredentials, if you do not want to have the encrypted credentials written back to the properties file.
-url URL to access the configuration servlet. This URL consists of the host name, the base URI as specified during installation (for example /wps), and the servlet extension /config.
-out 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.


XML Syntax for using a secure connection with SSL

To use the XML command line client with SSL over a secure HTTPS connection...

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 set ups that 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.

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.
-trustpwd Password that is required for accessing the truststore. If the default Java cacerts truststore is used, no trust password needs to be provided.
-trusttype Type of the truststore 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.
-keypwd Password that is required for accessing the keystore. If the default Java cacerts keystore is used, no key password 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.


SSL connection using the WAS default certificate stores 

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 the example above to run, use the trusttype parameter with a value of PKCS12 to avoid an invalid file format error.


SSL connection using the WAS dummy certificate stores 

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 WAS using the DummyServerKeyFile.jks and the DummyServerTrustFile.jks for secure connections. The option require client authentication must not be active.


Provide a key file for client authentication

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

When running on the Oracle Solaris platform, the default protocol handler for the hybrid IBM JDK is the Sun handler. Therefore, in order to successfully connect by using xmlaccess.sh and the IBM JSSE2 provider, edit the file $PORTAL_HOME/bin/xmlaccess.sh and add an additional parameter... 

${JAVA}                                                              

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


Export and import credential vault data

  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 configuration changes and restart the portal server.

  5. Export: 

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

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

Export using HTTPS:

Use the same passphrase for both export and import

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

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


XML input and output

XML files must always be in UTF-8 encoding and must a root element and schema: 

   
<?xml version="1.0" encoding="UTF-8"?>

   <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:noNamespaceSchemaLocation="PortalConfig_7.0.0.2.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.

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 OS and active locale. It may therefore be invalid XML.


Exports vs. imports

Syntax is the same for both exports and imports: We specify an XML file as input to xmlaccess.sh, which returns an XML file as output.

Request types include:

When importing, action attributes include:


Export a configuration, or part of it, and then import to another environment

  1. Run xmlaccess.sh with request type of export.

    You can use one of the XML sample files for the input file.

    The output file will have update set for the request type, and locate or update for the individual resources actions, and will be 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 xmlaccess.sh, specifying XML file.

    You can also use one of the XML sample files with request type update.

  4. xmlaccess.sh returns a result file indicating whether resources were imported successfully.


Transfer a complete configuration

To move a complete configuration from a test to a production server, use ReleaseBuilder with the sample file ExportRelease.xml.

The attribute domain="rel" indicates that only shared (as opposed to private) resources are exported.


Export and transfer parts of a portal configuration

To export partial configurations specify the XML hierarchy down to the specific portal resource that 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...

Note that this page does not exist in a newly installed portal. You can create it by executing the DeployPortlet.xml sample file.

Specify resources to export using object IDs or unique names. Use the Custom Unique Names portlet to look up object IDs and unique names of portal resources.

Executing ExportPage.xml 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. If the object IDs are correct, the referenced resources can 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.

Export 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. 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 part of the predefined administration page hierarchy that was created during the portal installation.

Use wildcard characters:

When you export portal resources, you can specify the asterisk (*) as a wildcard character for tag attributes. Be aware of the following limitations:

  1. The asterisk wildcard character is supported for attributes of top level tags only, that is subtags of the portal tag.

  2. Specify the asterisk wild character for the object ID attribute of tags as follows: objectid='*', except for policy-node tags, where you can specify it for the path attribute.

  3. Specify only the asterisk alone: "*". The asterisk does not work in combination with partial strings that precede or follow it. For example, you cannot specify "abc*" or "*xyz".

  4. If you specify the asterisk as a wildcard character, all other attributes of that tag are ignored, except for the following tags, where the listed attributes are interpreted as filters:

    • The tag content-node, attribute create-type

    • The tag tag, attribute locale .

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 modify resources

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

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. 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 XML scripts.

Other examples...


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

If you delete a page with an object ID and then use xmlaccess.sh to re-create the same page with the same object ID, you might receive an error message indicating the operation was canceled because it would have caused a duplicate key value.

xmlaccess only schedules the task to be run in WAS and returns. WAS does not necessarily run the task immediately. To determine when a task started and ended, check the portal SystemOut.log for messages:

These messages confirm that the cleanup task has successfully completed.

After confirmation, you can run the XML script for re-creating a page with the same object ID as it had before the deletion.


Register 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 xmlaccess.sh. Use the sample file RegisterPreDeployedEAR.xml to install a predeployed portlet. You might have to change this sample for requirements. For more information about how to predeploy portlets refer to the topic about predeployed portlets in this information center.


Deregister 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. Check the list and remove all users and groups you want to keep in the portal database. For example, keep the muted users and re-enable their passwords. After you have done this, import the file into the 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.


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


Parent


XML configuration interface
About xmlaccess.sh
v6.0 post migration steps for web content
V6.1 Web content post migration steps
V6.1 Web content post migration steps
V6.1 Web content post migration tasks
V6.1 Web content post migration steps
V6.1 Web content post migration tasks


Related tasks


Export configuration for migration to a remote server
Changes to xmlaccess.sh for this version of portal
XML configuration reference
Sample XML configuration files


+

Search Tips   |   Advanced Search