Level: Intermediate Sukumar Konduru, Advisory Software Engineer, IBM Dallas, Developer Technical Support Center
28 Aug 2002 The XML 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.
© 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.
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
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
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.
Download | Name | Size | Download method |
|---|
| editportlet.zip | 9 KB | FTP |HTTP |
Resources
About the author | | | Sukumar
Konduru is an Advisory Software Engineer at the IBM Dallas,
Developer Technical Support Center. He holds M.S in Computer
Science from University of Houston. You can reach Sukumar
Konduru at konduru@us.ibm.com. |
Rate this page
| 
