The world of WebSphere Portal Administration and configuration can be full of tedium and frustration. If you've ever manually constructed trees of portal places and pages, complete with containers and rows and portlets, you may have initially been quite satisfied with yourself. But the satisfaction may have turned rapidly into complete frustration when the portlet you painstakingly set permissions failed to appear when and where you expected it to!

Is it an inheritance problem? Is my portlet activated? Will I meet the deadline for duplicating all of this in both QA and Production? Luckily, WebSphere Portal ships with several useful tools for automating configuration and repetitive administrative tasks. One of the most useful and quickest to understand is XMLAccess.

No-Sweat Solution
XMLAccess is a command-line batch-processing utility that is incredibly useful for exporting and importing various portal configurations. It can be used for backing up the configuration of certain environments, for loading new configurations (for new portlets or pages, for example), or for updating existing portlets when a new WAR file is provided by development. Perhaps most important, this tool greatly eases the duplication of a portal environment from server "A" to server "B." For example, do you need 20 identical Portal Unit Test environments for that new development team? No sweat with XMLAccess.

There are two basic requests that can be made of this interface.

Export requests - tells the utility to export complete or partial portal configurations. This makes no changes, it only retrieves the specified configuration and spits it out to an XML file.

Update requests - Yep, you guessed it. This request takes a specified XML file and imports it into the portal configuration database. This process modifies the configuration of the portal based on the values in the imported XML file.

XMLAccess connects to the portal configuration URL over HTTP (usually something like: http://portal.example.com/wps/config

It therefore can potentially be executed from your workstation or from your home PC, so is very useful for those "working from home" days.

Straightforward Syntax
The XMLAccess command line syntax is very straightforward. For example, if you're on a Windows machine, with a portal was installed at C:\WebSphere\PortalServer, then of course the utility is located on your portal server at C:\WebSphere\PortalServer\bin.

To execute it, you must provide some key bits of info. First specify which XML file you're sending to the utility for instructions on what it should do:

xmlaccess.bat -in C:\temp\inputfile.xml

Next, tell the utility which portal config URL it should connect to in order to execute the instructions contained in that import.xml file. Give it the WPS Admin user ID and password in order to make the changes:

xmlaccess.bat -in C:\temp\inputfile.xml -user wpsadmin 
-pwd wpsadminpwd -url
 http://portal.example.com/wps/config

Finally, tell the utility where to direct the output of your action:

xmlaccess.bat -in C:\temp\inputfile.xml -user wpsadmin 
-pwd wpsadminpwd -url
 http://portal.example.com/wps/config -out C:\temp\outputfile.xml

Voila! When you execute this command, you'll get an output file containing the information you asked for in the inputfile.xml file. Easy, huh?

Export Entire Portal Config
Now that you know the basic syntax, let's look at the very first task in learning to use XMLAccess, which is to produce an export of an existing portal server configuration. This is a very simple XML file construct.

The output of a full export will contain everything that is configured in the portal. This will include all portlets, all pages, all permissions, etc. To produce a full export, you first need the XML file that will instruct XMLAccess to generate this export:

<?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"
  export-users="false">
  <portal action="export"/>
</request>

This is a very simple XML file with the standard header/schema info. The meat here is the portal element with an action of export. There is a sample of this file on your portal server. It's called C:\WebSphere\PortalServer\doc\xml-samples\export.xml

Create this xml file in a text editor or use the sample. Let's call this file C:\temp\export.xml

Change directory to C:\WebSphere\PortalServer\bin and execute the following:

xmlaccess.bat -in C:\temp\export.xml -user wpsadmin 
-pwd wpsadminpwd -url
 http://portal.example.com/wps/config -out C:\temp\full_exported_config.xml

This will produce a file in C:\temp called full_exported_config.xml containing the entire portal repository configuration. View it in Wordpad or Textpad and you will see all of the components defined to this portal. Once complete, you should see the following message:

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

If this export fails for some reason, the failure will be output to the console. Generally speaking, this task will fail if the user/password info is incorrect or if the portal is unavailable-or if you're using the wrong port in the -url section).

Export Partial Portal Config
But what if you don't want to export the entire configuration of the portal? Let's say you only want to export the configuration of your new page with only the components you placed on that page.

Your page is a "content-node" in XMLAccess parlance. If you look at the full export you did above, toward the bottom you'll see all of the default out-of-the-box content-nodes defined in that file (Welcome, My Work, My Finances, etc).

Each default content-node has a unique name defined for it in the portal config. Any new content-nodes that you may add (such as newpage1) will not, by default, have a consistent uniquename. It is a good idea to define one for your new page before we continue. This will make it much easier to locate your page in the config file.

Let's say your page is called newpage1. You created it in the Manage Pages section of the portal admin console and you placed it under Content Root->My Portal. That is, it is at the same level as the default 'Welcome' page.

Give this new page a unique name by going to Portal Settings->Custom Unique Names in the portal admin console. Select Pages as the Resource Type, find your newpage1 (it's probably on the very last page of the list) and click the pencil icon to edit the unique name.

Let's give newpage1 the unique name of wps.My Portal.newpage1. From now on, instead of referring to your page as some enormous (and changing) value in the XML, we can locate it by this name.

To export just your newpage1 configuration, you would create a new XML file. Let's call this one newpage1_export.xml. This new file would contain the following:

<?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">
  <portal action="locate">
    <content-node action="export"
      uniquename="wps.My Portal.
      newpage1" export-descendants="true"/>
  </portal>
</request>

Notice we're only "locating" the portal configuration initially, whereas before we exported it. Once we locate the portal config, we drill in further and do an export on the content-node named wps.My Portal.newpage1.

Execute this as follows:

xmlaccess.bat -in C:\temp\newpage1_export.xml -user wpsadmin 
-pwd wpsadminpwd -url
 http://portal.example.com/wps/config -out C:\temp\partial_exported_config.xml

We now have just your newpage1 configuration exported to C:\temp\partial_exported_config.xml.

So simple. Following this methodology (and using the helpful sample files in C:\WebSphere\PortalServer\doc\xml-samples), we can export a single portlet, a theme configuration, permissions, etc.

Import Full Portal Config
Now that you have your exported config, perhaps you'll want to import it into a fresh new portal. Let's pretend that we have a portal on a new Windows machine and that it was created with an empty configuration, using the -W installPortletsSequence.active="false" option. (For more info on how to do this, consult the Portal InfoCenter).

There are no pages or labels or portlets defined with this blank portal. You first take your full export (generated earlier), and transfer the file over to the new portal. Stick this file in C:\temp.

Remember, you only have the desired configuration definition in your full_exported_config.xml file. The actual WAR files and themes and skins files are not in the XML file. You have to make sure that any portlets or themes or skins that are defined in this config file have corresponding physical files on the server. For example, if you have a definition for portletabc.war in our config file, then you have to ensure that portletabc.war is actually located on the server we plan to import the config on.

By default, the portal will assume that portlet WARs will be located in C:\WebSphere\PortalServer\installableApps. The portal will likewise assume that files for the themes and skins are located in the default locations.

Once you verify that all the necessary portlet WARs and theme files are in place, you can execute the import:

xmlaccess.bat -in C:\temp\full_exported_config.xml -user wpsadmin 
-pwd wpsadminpwd -url
 http://portal.example.com/wps/config

Note that you don't necessarily have to specify an output file. After all, you're importing a config in this step. If you specified an output file using the -out flag, the console output would be written to this file. Once you execute this and restart your portal, you should see the entire config from portal A now transferred to your new portal B.

Import Partial Portal Config
If you are importing the partial config generated above, you need to be aware that you're only importing that single newpage1 and the pieces contained under it. You're not importing the parent content-node for our newpage1, but instead assuming it is already there.

When you exported the partial config, you produced: C:\temp\partial_exported_config.xml that should look something like this:

<?xml version="1.0" encoding=
  "UTF-8"?>
<request
type="update" xmlns:xsi=http://
  www.w3.org/2001/XMLSchema-
  instance xsi:noNamespaceSchema
  Location="PortalConfig_1.3.xsd">

  <portal action="locate">
<skin action="locate" objectid="_K_0830MR0T4A0I1P9R_37 Outline"
uniquename="wps.skin.outline"/>
<theme action="locate" objectid="_J_0830MR0T4A0I1P9R_3B WebSphere"
uniquename="wps.theme.webSphere"/>
<content-node action="locate" objectid="6_0_A Content Root"
uniquename="wps.content.root"/>
<content-node action="locate" objectid="_6_0830MR0T4A0I1P9R_35 My Portal"
uniquename="wps.My Portal"/>

<content-node action="update" active="true" allportletsallowed="true"
 content-parentref="_6_0830MR0T4A0I1P9R_35 My Portal" create-type="explicit"
  objectid="_6_0830MR0T4A0I1P9R_CI newpage1" ordinal="900" skinref="undefined"
   themeref="_J_0830MR0T4A0I1P9R_3B WebSphere" type="page" 
   uniquename="wps.My Portal.newpage1">
    </content-node>
  </portal>
  <status element="all"
    result="ok"/>
</request>

You can see how you're running a "locate" on the Content Root content-node and the My Portal content-node. If those nodes don't already exist in the new portal, then the partial import of newpage1 will fail. The same is true for the skins and themes and any portlets that may be defined on our newpage1.

If all the objects that you're "locating" are found, then your newpage1 will be created in the appropriate spot when you run the import on portal server 'B':

xmlaccess.bat -in C:\temp\partial_exported_config.xml -user wpsadmin 
-pwd wpsadminpwd -url
 http://portal.example.com/wps/config

Log into and you should see newpage1. Brilliant!

As you tinker with importing and exporting, you'll discover how easy it is to update access permissions, add or update portlets, add or update themes, skins and the like. The example files in C:\WebSphere\PortalServer\doc\xml-samples are your starting point for these other activities. Also of great use are the InfoCenter documents regarding XML Access. These pages are currently located at http://publib.boulder.ibm.com/infocenter/wp51help/ topic/com.ibm.wp.ent.doc/wps/admxlai.html.