XML configuration interface - Changes for WebSphere Portal Version 5.0.2

This topic describes the changes in the XML configuration interface from WebSphere Portal Version 4.2 to WebSphere Portal Version 5.0.2.

The syntax of XML scripts has undergone major changes between Version 4.2 and Version 5.0.2 of WebSphere Portal.

 

Changes to the XML command line syntax

The command line client has a new syntax. Arguments are now identified by options and not by order:

xmlaccess -user wpsadmin -pwd wpsadmin -in file.xml -out result.xml -url myhost:8082/wps/config

An output file is now defined by using the optional command line argument -out result.xml. If you want to re-import the XML output later use that option during the export instead of redirecting console output. Otherwise problems with character encodings will occur. Save the XML output file for later re-import.

 

Changed schema and XML script format

The XML syntax is now defined in an XML Schema and not in a DTD. XML scripts must have the following format: 

   <?xml version="1.0" encoding="UTF-8"?>
   <request
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="PortalConfig_1.2.xsd"
    type="export | update">
     . . . configuration . . .
   </request>

A mandatory type attribute has been introduced; possible values are export for an export request (locate and export actions) and update for an update request (locate, create, update and delete actions).

The different versions of WebSphere Portal use the following syntax definitions for the XML configuration interface:

Version XML schema DTD public identifier DTD public identifier
5.0 PortalConfig_1.2.xsd n/a n/a
4.2 n/a -//IBM//DTD Portal Configuration 1.1//EN PortalConfig_1.1.dtd
4.1 n/a -//IBM//DTD Portal Configuration 1.0//EN PortalConfig.dtd

 

Migrate your XML scripts

XML scripts from WebSphere Portal Version 4 are not compatible with Version 5.0.2. Before you can run XML script from Version 4, convert them to be comply with Version 5.0.2. To help you convert existing XML scripts, a style sheet is provided to convert them. The style sheet is convert42to5.xsl. It converts XML scripts from WebSphere Portal Version 4.1.2 and later to the correct format for Version 5.0.2. If you want to use XML scripts from versions of WebSphere Portal earlier than Version 4.1.2, you need to first convert them from Version 4.1 to Version 4.2 using the style sheet shipped with Version 4.2. You then convert the resulting XML script from Version 4.2 format to Version 5.0.2 format using the convert42to5.xsl style sheet.

The syntax for converting XML scripts that are in the Version 4.2 format to the new Version 5.0.2 format is as follows:

For iSeries systems: 

   wp_root/bin/convert42to5.sh input_file_version_4.2 output_file_version_5

where

      wp_root is the directory path of your WebSphere Portal Version 5.0.2 installation.
      input_file_version_4.2   is the name of the XML script that complies with Version 4.2.
      output_file_version_5 is the name of the resulting XML script that complies with the format of Version 5.0.2 XML scripts.

The converted scripts will be in valid syntax for Version 5.0. However, due to semantic changes as described in the following sections, converted scripts will often not produce the same effect in Version 5.0.2. In particular, note the following points:

  1. Access control in Version 5.0 is significantly different from Version 4. The conversion script creates new access control definitions that are mostly equivalent to Version 4 access permissions in the input script. However, the resulting access control configuration does not make use of the new inheritance concept for access control.
  2. In the XML format for Version 4.2, information about the layout and content of a page and about the portal navigation structure were separated. The XML format for Version 5.0.2 combines the navigation and content information in one resource. Therefore the stylesheet can only convert page definitions properly if the 4.2 XML contains information about the navigation link to the page which is contained in the root composition. Note that a regular 4.2 export of a page does not contain this information. As a solution either export the relevant part of the root composition as well, or add the navigation definitions manually.
  3. The lookup mechanism has changed for many resources in the Version 5.0.2 XML configuration interface. If you use XML scripts to export, modify or delete existing resources in the portal, especially pages, skins and themes, you might need to assign them unique names to properly identify those resources. See the XML configuration interface reference documentation for more details.

 

New resources in Version 5.0.2

WebSphere Portal Version 5.0.2 supports event handlers, URL mappings and property broker wires as new core resources. These resources can be imported and exported using the XML configuration interface.

In Version 5.0.2 you can also manage users and groups with the XML configuration interface, including the access control settings that are configured for them in the portal.

 

Portal settings

The portal settings contained in the global-settings and services-settings XML elements are significantly different between WebSphere Portal Version 4 and Version 5.0.2. If you have XML scripts from WebSphere Portal Version 4 which modify these settings and you want to migrate these XML scripts for use in Version 5.0.2, you need to insert the appropriate key names and values for Version 5.0.2 into the scripts. See Portal service configuration for more information about these keys and their values.

 

New Object IDs and Unique Names

In WebSphere Portal Version 5.0.2 there are new objectid and uniquename attributes on almost all resources. Several resources, such as pages, themes, and skins do not have a name attribute, that is an administrative name, any more. Instead they support a unique name which is guaranteed to be unique in the installation. This unique name is therefore more useful for selecting resources in XML scripts. Using the XML configuration interface for porting pages that have duplicated administrative names is possible without conflicts. As a consequence, the attributes that can be used to look up resources in the portal have changed. See the XML reference documentation for more information on lookup of portal resources. In WebSphere Portal Version 5.0.2 you can identify a resource uniquely by specifying its object ID.

You can now export and import database object IDs across portal installations using the XML configuration interface without conflicts resulting from identical object IDs. This way you can transfer resources between installations without changing their object IDs.

The whole concept of handles has been replaced by object IDs used for expressing references. The handle and handleref attributes have been removed. All reference attributes, such as portletref in portlet instances, refer to object IDs instead. Object IDs in XML files can either be real database IDs that are stored in the portal database, or they can be symbolic strings that express only links in the XML file, similar to the handles in WebSphere Portal Version 4.2.

The XML configuration interface supports an ID generating mode, in which all object IDs are treated as symbolic. This behavior is essentially equivalent to the use of handles in WebSphere Portal Version 4.2. Therefore you can keep references in XML files intact by using this mode and renaming all handle attributes to objectid. The ID generating mode can be turned on by specifying the attribute create-oids="true" in the main request element.

See the reference documentation for more information on the handling of object IDs in the XML configuration interface.

 

Access control

In WebSphere Portal Version 4, access rights on resources were specified by access-right sub-elements of the resource. Access control in WebSphere Portal Version 5.0.2 is conceptually different from Version 4. It is based on roles, not on permissions, and it is inherited along resource hierarchies. See the access control migration documentation on how the old concepts relate to the new access control.

With the new access control introduced in WebSphere Portal Version 5.0.2, the access-right tag has been removed. Instead, resources that support access control now have one access-control sub-element under which all information related to access control is combined. See the reference documentation and XML examples on how to specify access control definitions in XML in WebSphere Portal Version 5.0.2.

The resources that support access control definitions in XML have changed from WebSphere Portal Version 4 to Version 5.0.2:

In WebSphere Portal Version 4, the XML configuration interface supported only access control on individual resources but not on the resource type permission that applied to all resources of a given type. In WebSphere Portal Version 5.0.2, virtual resources allow to assign user roles on all resources of a given type.

 

Portlet applications

The naming of the portlet application elements has been revised. It is now more consistent with the portal user interface and the deployment descriptors:

 

Page definitions

The representation of the page hierarchy structure has changed significantly between WebSphere Portal Version 4 and Version 5.0.2. All portal content is now represented as a tree of content nodes which can represent pages or URL references. In the XML structure, these are all expressed as content-node elements, which are linked into a tree structure by content-parentref attributes.

A new content node must always be linked to an existing parent in the content tree when it is created. Consequently, you can no longer inadvertently create pages using the XML interface that are not linked into the portal navigation and are therefore not accessible for the administration portlets.

The XML configuration interface now also allows you to export a subtree of the content hierarchy (for example a root page with all contained pages) with one single XML request. See the examples for more information.

 

Changes from both Versions 4.1 and 4.2 to Version 5.0.2

The owner and system attributes of pages and the active and editable attributes of components have been removed. The parentref attribute of pages has been renamed to derivation-parentref. All content nodes now have an ordinal attribute which represents their ordering in the content tree.

Ordinals on both content nodes and components now support a special syntax that makes it possible to specify their relative position instead of a hard coded integer value. This means that you can, for example, insert a new page into a label at the last position without having to care about the ordinal values of other pages in that label.

 

Changes from WebSphere Portal Version 4.1 to Version 5.0.2

In WebSphere Portal Version 4.1 the portal navigation structure was expressed as pagegroup XML elements referring to the contained pages. In Version 5.0.2, there is a hierarchy of content-node elements with different types. The pages have a content-parentref attribute referring to the containing parent page. Deleting a content node will automatically remove all its descendants.

The component types row and column have been combined into a type container with an additional orientation attribute. This attribute can take the following values:

The existing name attribute of components has been renamed to ordinal.

 

Changes from WebSphere Portal Version 4.2 to Version 5.0.2

In Version 4.2 the portal navigation structure was expressed as a tree of components of type layered inside the special composition Root.Composition. Places were represented as components in that hierarchy; pages were represented as navigation links that referred to a composition element containing the page layout. Configuration data for the page was stored in both the navigation link and the actual composition.

In WebSphere Portal Version 5.0.2, labels and pages are both content-node elements with different types. They are organized in a tree that is expressed by their content-parentref attributes. The navigation structure in the portal is the same as the structure of this content tree. There is no root composition defined in the XML scripts anymore.

As the navigation structure is not expressed by a component tree anymore, the component type layered has been removed from the XML syntax. All component configuration data that applied to layered components only, has also been removed:

The component type unlayered has been renamed to container.

 

Web services

WebSphere Portal Version 5.0.2 does not support Web services. All the corresponding XML elements and attributes have been removed from the XML syntax:

See also