© 2002 International Business Machines Corporation. All rights reserved.

Introduction

The XML Access configuration client interface included with WebSphere Portal Version 4.1 allows exporting entire or partial configuration settings as an XML file and recreating configurations by importing the XML file. This interface can also be used as an alternative to performing some administrative tasks as part of the Portal Administration place and the Work with Pages place within the portal server.

The supported tasks of the XML Access interface include creating and updating the following resources:

• Portlet applications
• Portlets
• Themes and Skins
• Markups and Client device definitions
• Places and Pages
• Credential Segments and Slots

The WebSphere Portal installation process generates a request file named SetupPortal.xml, and uses it to create default resources like pages and portlets into the Portal.

This article provides step by step instructions for creating an XML request configuration file to install a sample portlet, create a page and page group, and how to run the XML Access tool to update portal server.

Back to top

What is XML Access?

XML Access is a command line utility available as a Java interface that ships with WebSphere Portal. This utility consists of a small HTTP client to the portal server that can be copied from the machine where WebSphere Portal is installed to another machine and run remotely to update the portal configuration. You will need to copy both the xmlaccess.bat (xmlaccess.sh for Unix environments) and the xmlaccess.jar file. You may have to alter the BAT of SH file to conform with the remote system's environment.

The XML Access tool is invoked by executing PortalServer\bin\xmlaccess.bat. The XML Access syntax is as follows:

xmlacccess <XML file> <userid:password> <portal config URL>

Where:

• <XML file> - the XML request file name. This must either be local to the target server, or a valid HTTP URL if performing a remote update.
• <userid:password> - the userid and password of a portal user with manage rights for "any portal".
• <portal config URL> - consists of the host name, and the base portal URI appended with /config

An example for the above command is as follows:

xmlaccess input.xml wpsadmin:wpsadmin http://sukumar.ibm.com/wps/config

Running the above command produces an XML document that contains configuration or status of an "update" or "create" request for portal resources. The output is sent to standard output that can then be redirected to a file. The output follows the same XML format as that of the input request file.

Note: This tool sends the userid and password as clear text and it is not advisable to run this utility across a public network.

Back to top

Specifying the XML schema and root element

The input request XML file can be created using any text editor and it should follow the specifications of the PortalConfig.dtd located in the PortalServer\app\wps.ear\wps.war\dtd\ directory. The root element of this XML document is named <request>. The <portal> sub-element is used to import or export portal resources. The <portal> element's action attribute should have a value of either "locate" or "export". To update the portal server configuration, the value should be "locate". The XML fragments listed in the following sections should be inserted inside the <portal> element to complete the XML input file. Also note that the encoding of the input XML must always be UTF-8.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE request PUBLIC "-//IBM//DTD Portal Configuration 1.0//EN" "PortalConfig.dtd"> 
<request> 
  
   <portal action="locate"> 
     <!-- XML fragments detailed in the following sections to be inserted here. --> 
 
  </portal> 
</request>

Back to top

Installing the portlet

The <package> element corresponds to an abstract portlet application and it is used to install portlet applications. The action attribute of the <package> element can be either "update", or "create" to install a portlet application. If the portlet application is already installed, the action attribute with a value of "create" might fail, since the globalid attribute should be unique. Its <URL> sub-element points to the location of WAR file to be installed.

To install this sample portlet onto your portal server, copy the file editportlet.war to the C:\mysampleportlets directory on your system.

The <access-right> element has been specified for both the concrete portlet application and the concrete portlet. The wpsadmin user and all users that are part of the wpsadmins group have been authorized to both manage and delegate permissions. The combination of subjectid=any and subjecttype=user refers to all logged in users and they are given rights to edit both the portlet application and the portlet. Anonymous users are permitted to only view the portlet.

Here are the matching rules between elements of the request XML file and those of the portlet.xml:

• The <package> element's globalid attribute should be the same as the <portlet-app> element's uid attribute specified in portlet.xml.
• The <application> element's globalid attribute should be same as the <concrete-portlet-app> element's uid attribute specified in portlet.xml.
• The <portlet> element's name attribute should be the same as the contents of the <portlet-name> element specified in portlet.xml

<package action="update" active="true" globalid="samplepkg.EditPortlet"> 
  <url>file:///C:\mysampleportlets\editportlet.war/url> 
  <application action="update" active="true" globalid="
         samplepkg.EditPortlet.concrete" > 
    <access-right permission="delegate" subjectid="wpsadmin" 
       subjecttype="user" update="set"/> 
    <access-right permission="manage" subjectid="wpsadmin" 
       subjecttype="user" update="set"/> 
    <access-right permission="delegate" subjectid="wpsadmins" 
       subjecttype="user-group" update="set"/> 
    <access-right permission="manage" subjectid="wpsadmins" 
       subjecttype="user-group" update="set"/> 
    <access-right permission="view" subjectid="any" 
       subjecttype="anonymous-user" update="set"/> 
    <access-right permission="edit" subjectid="any" 
       subjecttype="user" update="set"/> 
    <portlet action="update" handle="editmemoportlet" 
       active="true" name="Edit Memo concrete"> 
      <access-right permission="delegate" subjectid="wpsadmin" 
         subjecttype="user" update="set"/> 
      <access-right permission="manage" subjectid="wpsadmin" 
         subjecttype="user" update="set"/> 
      <access-right permission="delegate" subjectid="wpsadmins" 
         subjecttype="user-group" update="set"/> 
      <access-right permission="manage" subjectid="wpsadmins" 
         subjecttype="user-group" update="set"/> 
      <access-right permission="view" subjectid="any" 
         subjecttype="anonymous-user" update="set"/> 
      <access-right permission="edit" subjectid="any" 
         subjecttype="user" update="set"/> 
    </portlet> 
  </application> 
</package>

Back to top

Creating a page and customizing it to have the portlet

The <page> element defines the layout of a page. The handle attribute assigns an identifier to the page element. This is needed so that page group can identify the page and add it as part of its group. The <component> element can be of type "column", "row", or "control". The <portletinstace> element refers to an instance portlet on the page and is embedded in a component of type control which is included in a component of type column.

The <portletinstance> element's portletref attribute points to the portlet that was installed in the previous section. The portletref attribute should be the same as the handle attribute of <portlet> element.

<page action="update" active="true" handle="editDemoPg" name="Edit portlet demo page" 
     owner="wpsadmin" system="false"> 
  <supported-markup markup="html" update="set"/> 
  <localedata locale="en">
      <title>Edit Demo Page/title>
  </localedata> 
  <access-right permission="delegate" subjectid="wpsadmin" 
     subjecttype="user" update="set"/> 
  <access-right permission="manage" subjectid="wpsadmin" 
     subjecttype="user" update="set"/> 
  <access-right permission="delegate" subjectid="wpsadmins" 
     subjecttype="user-group" update="set"/> 
  <access-right permission="manage" subjectid="wpsadmins" 
     subjecttype="user-group" update="set"/> 
  <access-right permission="view" subjectid="any" 
     subjecttype="anonymous-user" update="set"/> 
  <access-right permission="edit" subjectid="any" 
     subjecttype="user" update="set"/> 
  <component action="create" active="true" nestable="false" 
     name="-1" type="column" > 
     <component action="create" active="true" 
       <name="100" type="control" > 
        <portletinstance action="update" portletref="editmemoportlet"/> 
      </component> 
  </component> 
</page>

Back to top

Creating a page group

This XML fragment creates a page group labeled as "testPgGroup". It also adds a page created in section 4 to the page group. The page is referenced in the <pagegroup> element by using the "handle" that is defined while creating the page. The <pageref> element's ordinal attribute determines the order in which a page is displayed relative to other pages in the same page group. The ordinal attribute can also be defined to the <pagegroup> element to display page groups in any order.

<pagegroup action="update" active="true" default="true" ordinal="10000" name="testPgGroup"> 
  <pageref page="editDemoPg" ordinal="1000" update="set"/> 
  <localedata locale="en"> 
    <title>Test Page Group/title> 
  </localedata> 
  <supported-markup markup="html" update="set"/> 
  <access-right permission="delegate" subjectid="wpsadmin" 
     subjecttype="user" update="set"/> 
  <access-right permission="manage" subjectid="wpsadmin" 
     subjecttype="user" update="set"/> 
  <access-right permission="delegate" subjectid="wpsadmins" 
     subjecttype="user-group" update="set"/> 
  <access-right permission="manage" subjectid="wpsadmins" 
     subjecttype="user-group" update="set"/> 
  <access-right permission="view" subjectid="any" 
     subjecttype="anonymous-user" update="set"/> 
  <access-right permission="edit" subjectid="any" 
     subjecttype="user" update="set"/> 
</pagegroup>

Back to top

Preparing the XML file and running XML Access

Now we will put all the pieces together. Embed the contents of the previous three sections inside the <portal> element shown in the section Specifying the XML Schema and root element. Save the resulting file as input.xml. You may also download the complete input.xml file. Open a command window and change to the directory where you saved the input.xml file. Add the Portal server's bin directory to your PATH environment in order to locate the XML Access tool. Run the following command by substituting the appropriate userid, password, and server URL.

xmlaccess input.xml userid:password http://machine.domain.com/wps/config

XML Access opens an URL connection to a servlet that serves the webpath "/wps/config" and sends the input.xml to the servlet. The servlet verifies the validity of XML file and updates the portal server. The output of the command itself is XML data that follows the same schema specified in the input.xml.

Note: If you encounter any problems when running the tool, enable logging by the setting the baseGroup.XMLAccessTraceLogger.isLogging property to "true" in the file -- WebSphere\AppServer\lib\app\config\jlog.properties. Restart portal server and try the XML Access command again. The resulting log file can be found in the directory PortalServer\log. Open the most recent log file to see the details of what transpired during the XML Access execution. .

Back to top

Accessing the page

Login to the portal and switch to the Test Page Group. You should see a page labeled Edit Demo Page.

Back to top

Conclusion

You have just learned how to use the XML Access utility to install a portlet and create a page and page group. The sample request XML file can be extended to install multiple portlets and create multiple page groups. The administrator can use this request XML file to quickly update multiple WebSphere Portal server instances. Installing themes and skins can also be performed using the tool and the concept is similar to other tasks mentioned in this article.

Back to top

Download

Name	Size	Download method
editportlet.zip	9 KB	FTP|HTTP

Information about download methods

Resources

• WebSphere Portal Info Center
  
  

About the author

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• What is XML Access?
• Specifying the XML schema and root element
• Installing the portlet
• Creating a page and customizing it to have the portlet
• Creating a page group
• Preparing the XML file and running XML Access
• Accessing the page
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data.
• Article: See how DB2 pureXML schema capabilities can evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how to use DB2's pureXML to expose the native XML capabilities of DB2.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into WebSphere on developerWorks

Securing WebSphere Application Server environments

Essential resources to design and develop your WebSphere solutions in ways that will make them more secure.

Special offers