Contents


Developing an XML request file for XML Access in WebSphere Portal Version 4.1

Comments

© 2002 International Business Machines Corporation. All rights reserved.

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.

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.

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>

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>

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>

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>

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.

Figure 1 - Execution of XML Access command
Execution of XML Access command
Execution of XML Access command

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

Accessing the page

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

Figure 2 - Edit Demo Page in Test Page Group
Edit Demo Page in Test Page Group
Edit Demo Page in Test Page Group

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.


Downloadable resources


Related topic


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=13242
ArticleTitle=Developing an XML request file for XML Access in WebSphere Portal Version 4.1
publish-date=08282002