Welcome!

IBM Cloud Authors: Zakia Bouachraoui, Elizabeth White, Yeshim Deniz, Pat Romanski, Liz McMillan

Related Topics: IBM Cloud

IBM Cloud: Article

XML Access 101

A look at WebSphere Portal Server 5.1

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.

More Stories By Chris Lockhart

Chris Lockhart is a senior technical resource at Perficient, a firm recognized for its expertise around IBM technologies. Chris has worked with IBM's WebSphere, Tivoli and Lotus Software platforms for more than 6 years. For more information, please visit www.perficient.com

Comments (1)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


IoT & Smart Cities Stories
The platform combines the strengths of Singtel's extensive, intelligent network capabilities with Microsoft's cloud expertise to create a unique solution that sets new standards for IoT applications," said Mr Diomedes Kastanis, Head of IoT at Singtel. "Our solution provides speed, transparency and flexibility, paving the way for a more pervasive use of IoT to accelerate enterprises' digitalisation efforts. AI-powered intelligent connectivity over Microsoft Azure will be the fastest connected pat...
There are many examples of disruption in consumer space – Uber disrupting the cab industry, Airbnb disrupting the hospitality industry and so on; but have you wondered who is disrupting support and operations? AISERA helps make businesses and customers successful by offering consumer-like user experience for support and operations. We have built the world’s first AI-driven IT / HR / Cloud / Customer Support and Operations solution.
Codete accelerates their clients growth through technological expertise and experience. Codite team works with organizations to meet the challenges that digitalization presents. Their clients include digital start-ups as well as established enterprises in the IT industry. To stay competitive in a highly innovative IT industry, strong R&D departments and bold spin-off initiatives is a must. Codete Data Science and Software Architects teams help corporate clients to stay up to date with the mod...
At CloudEXPO Silicon Valley, June 24-26, 2019, Digital Transformation (DX) is a major focus with expanded DevOpsSUMMIT and FinTechEXPO programs within the DXWorldEXPO agenda. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of business. Only 12% still survive. Similar percentages are found throug...
Druva is the global leader in Cloud Data Protection and Management, delivering the industry's first data management-as-a-service solution that aggregates data from endpoints, servers and cloud applications and leverages the public cloud to offer a single pane of glass to enable data protection, governance and intelligence-dramatically increasing the availability and visibility of business critical information, while reducing the risk, cost and complexity of managing and protecting it. Druva's...
BMC has unmatched experience in IT management, supporting 92 of the Forbes Global 100, and earning recognition as an ITSM Gartner Magic Quadrant Leader for five years running. Our solutions offer speed, agility, and efficiency to tackle business challenges in the areas of service management, automation, operations, and the mainframe.
The Jevons Paradox suggests that when technological advances increase efficiency of a resource, it results in an overall increase in consumption. Writing on the increased use of coal as a result of technological improvements, 19th-century economist William Stanley Jevons found that these improvements led to the development of new ways to utilize coal. In his session at 19th Cloud Expo, Mark Thiele, Chief Strategy Officer for Apcera, compared the Jevons Paradox to modern-day enterprise IT, examin...
With 10 simultaneous tracks, keynotes, general sessions and targeted breakout classes, @CloudEXPO and DXWorldEXPO are two of the most important technology events of the year. Since its launch over eight years ago, @CloudEXPO and DXWorldEXPO have presented a rock star faculty as well as showcased hundreds of sponsors and exhibitors! In this blog post, we provide 7 tips on how, as part of our world-class faculty, you can deliver one of the most popular sessions at our events. But before reading...
DSR is a supplier of project management, consultancy services and IT solutions that increase effectiveness of a company's operations in the production sector. The company combines in-depth knowledge of international companies with expert knowledge utilising IT tools that support manufacturing and distribution processes. DSR ensures optimization and integration of internal processes which is necessary for companies to grow rapidly. The rapid growth is possible thanks, to specialized services an...
At CloudEXPO Silicon Valley, June 24-26, 2019, Digital Transformation (DX) is a major focus with expanded DevOpsSUMMIT and FinTechEXPO programs within the DXWorldEXPO agenda. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of business. Only 12% still survive. Similar percentages are found throug...