Work with xmlaccess

 

+

Search Tips   |   Advanced Search

 

  1. XML configuration through administrative portlets
  2. xmlaccess.sh syntax
  3. Syntax elements of xmlaccess.sh
  4. XML syntax for using SSL
  5. XML syntax elements for using SSL
  6. XML syntax for exporting and importing credential vault data
  7. XML input and output
  8. Transfer a complete configuration
  9. Staging - transferring a release configuration
  10. Export and transfer parts of a portal configuration
  11. Create 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

The XML Configuration Interface, xmlaccess.sh, is used to export and import configurations.

XML samples can be found in...

There are two ways to work with portal configuration data...


XML configuration through administrative portlets

You can export a page or an entire page hierarchy by clicking the Export icon in the Manage pages administration portlet. You can import XML configuration files using the Import XML portlet.

You must enable support for JavaScript and disable pop-up blocking in your browser settings.


To export a page or an entire page hierarchy

  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.

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

You can import an XML configuration file by using the XML Import portlet.


To import an XML configuration file

  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.


xmlaccess.sh syntax

xmlaccess.sh connects to portal servers using HTTP or HTTPS, allowing remote configuration.

To run...

You can use xmlaccess.sh remotely from a machine that does not have portal installed, if the machine has a Java run time, and if you copy the four required files to the remote machine...

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

Basic syntax...

xmlaccess -user user_ID -password password -url http://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. Connect to xmlaccess.sh from inside a protected intranet. In all other networks use a secure HTTPS connection to connect to xmlaccess.sh.

Use the parameter askForCredential and leave out the parameters user and password to be prompted you for the user ID and password.

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

You can also place the credentials in a properties file and use the option useEncryptedCredentials to read the encrypted or unencrypted credentials from the properties file, and then save the file back using the encrypted password.

If you do not want to write the properties file back with the encrypted credentials, use the additional flag noUpdateProperties. In this case you can use the PropFilePasswordEncoder utility to encrypt the password in the properties file.

Properties read are:

For example...

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


Virtual portals

For virtual portals, to access...

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


Syntax elements of xmlaccess.sh

This section lists the syntax elements for using xmlaccess.sh over an HTTP connection. For information about the XML syntax elements for a secure HTTPS connection refer to XML syntax elements for using SSL.

Syntax element Description
xmlaccess ./xmlaccess.sh|bat
-in File containing the XML request (configuration export or update) to be processed.
-user and -password User identification and password describing the authority under which the request should be processed.

For user specify the short name. Full distinguished names (DN) are not supported.

xmlaccess.sh is only accessible to users that have...

  • manager role on the virtual resource XML_ACCESS
  • 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 Provide the user credentials in a properties file rather than with the XML command.
-noUpdateProperties Use with 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...

    host_name/base_URI/servlet_extension

...for example...

    host_name/wps/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 SSL

When you use the XML command line client with SSL over a secure HTTPS connection, the command syntax is as follows:

xmlaccess -user user_ID -password password 
          -url https://myhost:10035/wps/config/ 
          -in input_file.xml -out result_file.xml  
          -truststore trustStore -trustpwd trustPassword 
          -trusttype trustType [ -keystore keyStore 
          -keypwd keyPassword -keytype keyType ]

The following rules apply:

  1. The https:// prefix in the URL is required to allow the XML client to detect whether a secure HTTPS connection is required. The appropriate HTTPS port must be provided instead of the HTTP port.

  2. The options starting with the string trust are mandatory in all configurations where a custom certificate store is used for storing certificates required for secure connections. For setups which use the Java standard cacerts certificate store, the parameters starting with trust are optional.

  3. The options starting with the string key are optional. They are only required when client certificate authentication is used for establishing the SSL connection.

  4. The default value for -keytype and -trusttype is jks. Therefore the -keytype and -trusttype options are optional unless the used keystore or truststore uses a different format.


XML syntax elements for using 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.
-trustpwd 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.
-keypwd 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.

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

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.

The following is an example of how to use xmlaccess.sh 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: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, 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.

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

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 Sun 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 $PortalHome/bin/xmlaccess.sh and add an additional parameter -Djava.protocol.handler.pkgs=com.ibm.net.ssl.www2.protocol as follows:

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


XML syntax for exporting and importing 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:10035/wps/config/ 
          -truststore profile_root/config/cells/cellname/nodes/nodename/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 XML syntax elements for credential secret migration

The following is an example of how to use xmlaccess.sh to export/import credential secrets using HTTPS:

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


XML input and output

An XML file that you process must always be in UTF-8 encoding and must specify the following root element and schema:

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

   <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:noNamespaceSchemaLocation="PortalConfig_6.1.0.2.xsd"
            type="export|update">

            . . . configuration  . . . 

   </request>

For an XML export, specify export for the request type.

For an XML import, specify update for the request type.

When importing, the resources action attribute can have the following values:

XML output is written to the standard output. Use the -out option to write the output to a file in UTF-8 encoding.

Standard output console encoding depends on your operating system and active locale, and therefore could be invalid XML.

The command line syntax and XML processing is the same for both exports and imports. Specify an XML input file to xmlaccess.sh, and the XML configuration interface returns a resulting XML file.

Procedure for exporting and importing all or part of a configuration...

  1. Run xmlaccess.sh with a file that has a request type of export in it.

    The file returned by xmlaccess.sh specifies update for the request type, and locate or update for the individual resources actions.

  2. Modify the XML result file from the export as required.

  3. Run xmlaccess.sh, specifying the XML file from the export.

    xmlaccess.sh returns a result file that indicates whether the specified resources were imported successfully, or what errors might have occurred.


Transfer a complete configuration

This example exports the complete portal configuration (not including users).

Export users is not desirable when when systems are be configured to use the same user repository. Transferring users may be useful when transferring configurations between development installations.

  1. Create WebSphere Portal ServerA.

  2. Create WebSphere Portal ServerB as an empty portal.

    An empty portal has no portlets or no pages.

  3. Configure both servers to use the same user data store configuration, LDAP directory, LDAP base DN, and so on.

  4. Export ServerA configuration...

      cd profile_root/PortalServer/bin
      ./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 ServerA_config.xml.

  5. If you have installed portlets or applications in addition to the ones bundled with portal, copy the necessary WAR files from ServerA to...

      ServerB:profile_root/PortalServer/deployed/archive

    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.

  6. Verify that all URLs in the file ServerA_config.xml that resulted from the export are valid.

    All the files 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...

      profile_root/PortalServer/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
      • 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:

      ...and replace them with the following URLs...

        PortalServer_root/pzn/prereq.pzn/pznauthorportlet.ear/Personalization_Workspace 6.ear/pznauthorportlet.war</url>
        PortalServer_root/pzn/prereq.pzn/pznruleportlet.ear/Personalization_Lists 6.ear/pznruleportlet.war</url>

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

  7. If this is a clustered environment, modify the xml file to remove the entries...

    • global-settings
    • services-settings

  8. On ServerB, import the configuration to the ServerB production portal:

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

  9. For 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 -DWasPassword=password

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

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

  11. Restart the portal.

The production portal is now ready for use.


Transfer a release configuration

You can move a complete configuration from test to production server using releasebuilder.sh with ExportRelease.xml.

ExportRelease.xml exports the complete portal configuration without private resources as required by releasebuilder.sh. 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 a specific portal resource.

The element itself has an export action. Parents must be specified with a locate action.

The sample 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, covered in the next section.

Normally, you specify the resources that you want to export by their object ID or by their unique name. You can use the Custom Unique Names administration portlet to look up object IDs and unique names of portal resources.

Executing ExportPage.xml results in an XML file similar to ExportPageResult.xml, which can be used to update the page to the exported state. You can also use ExportPageResult.xml to re-create the page.

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

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.

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 if reference resources...

The page and all contained resources take their object IDs with them, so they have the same object IDs on the source and target system. You can avoid that by using the ID generating mode, where the object IDs in the input are not taken literally, but during the import process the resources obtain new object IDs.

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.

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 xmlaccess.sh to install new resources in the portal or as an alternative to the user interface for performing some administration tasks. 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.

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. 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 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. 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 the portal. Be aware that the XML scripts create these resources only in the portal database, so that they can be used in the portal.

In addition, you have to write the JSPs that perform the actual visualization and copy them to the resource directory specified in the XML before you can use the theme in the portal.

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

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

To add a new language to the portal, use the CreateLanguage.xml example.

To prepare for running this XML script, you have to insert resource bundles and, where applicable, JSPs for the new language.

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

  1. 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 aborted because it would have caused a duplicate key value.

  2. When you run the cleanup task, xmlaccess.sh 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 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 your requirements.


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.

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


Preparing the deletion of orphaned data

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


Parent topic:

xmlaccess.sh


Related concepts


About xmlaccess.sh
Changes to xmlaccess.sh for this version of portal
XML configuration reference
Sample XML configuration files