XML configuration interface - Changes for WebSphere Portal V5.1


This topic describes the changes in the XML configuration interface from previous versions of WebSphere Portal to WebSphere Portal V5.1.

The syntax of XML scripts has undergone only minor changes between V5.0 and V5.1 of WebSphere Portal. However, the changes from earlier versions, such as V4.1 to V5.1 are considerable.

 

Changes from WebSphere Portal V5.0 to V5.1

 

Changed schema

A new XML Schema V1.3. has been created. XML scripts must specify the new Vof the schema as follows:

   <?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 | update">
     . . . configuration . . .
   </request>

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

WebSphere Portal

V

XML schema DTD public identifier DTD public identifier
5.1 PortalConfig_1.3.xsd n/a n/a
5.0.2 PortalConfig_1.2.1.xsd n/a n/a
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

 

New common name attribute for user tag

A new attribute common name has been added to the user tag. This attribute is mandatory. The value for this attribute corresponds to the cn setting of the parameter tag.

 

New cleanup-users attribute for request tag

A new attribute cleanup-users has been added to the request tag. Use this attribute to remove users from the portal database that have been removed from the user registry or have been muted. For more details about deregistering users refer to Deregistering Users and Groups from WebSphere Portal.

 

New and changed resources in WebSphere Portal V5.1

In WebSphere Portal V5.1 new resource tags task and action have been introduced. For more details about these tags refer to the XML reference.

 

Changes for the support of JSR 168 and WSRP

The following changes have been made to the XML configuration interface in WebSphere Portal V5.1 for the support of the JSR 168 standard and for Web Services for Remote Portlets (WSRP).

For details about these new elements and how to use them, refer to XML reference and Using WSRP services.

 

Virtual portals: Changes in the usage of the XML configuration interface

WebSphere Portal V5.1 allows you to create and manage multiple virtual portals. If your configuration has virtual portals, you can only export and import a single individual virtual portal at a time by using the XML configuration interface. You need to specify a separate XML request for each virtual portal. You cannot use the XML configuration interface to export or import multiple virtual portals or an entire portal installation with virtual portals.

The access permissions for the XML configuration interface are limited to the master administrator of the portal installation as a whole. Subadministrators for the virtual portals cannot use the XML configuration interface to export or import the virtual portal which they administer.

 

Changes from WebSphere Portal V4.2 to V5.0.2

 

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. An example:

xmlaccess -user user -password password -url myhost:8082/wps/config -in XML_file -out result.xml

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

 

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

 

New resources in WebSphere Portal V5.0.2

From WebSphere Portal V5.0.2 on the XML configuration interface supports event handlers, URL mappings and property broker wires as new core resources. These resources can be exported and updated using the XML configuration interface.

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

 

Migrating your XML scripts

XML scripts from WebSphere Portal V4 are not compatible with V5.1. Before you can run XML script from V4, convert them to be comply with V5.1. 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 V4.1.2 and later to the correct format for V5.1. If you want to use XML scripts from versions of WebSphere Portal earlier than V4.1.2, first convert them from V4.1 to V4.2 using the style sheet shipped with V4.2. You then convert the resulting XML script from V4.2 format to V5.1 format using the convert42to5.xsl style sheet.

The syntax for converting XML scripts that are in the V4.2 format to the new V5.1 format is as follows:

For UNIX systems:

   wp_root/bin/convert42to5.sh input_file_version_4.2 output_file_version_5

For Windows systems:

   wp_root\bin\convert42to5.bat input_file_version_4.2 output_file_version_5

where

      wp_root is the directory path of your WebSphere Portal V5.1 installation.
      input_file_version_4.2   is the name of the XML script that complies with V4.2.
      output_file_version_5 is the name of the resulting XML script that complies with the format of V5.1 XML scripts.

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

  1. Access control in V5.0 is significantly different from V4. The conversion script creates new access control definitions that are mostly equivalent to V4 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 V4.2, information about the layout and content of a page and about the portal navigation structure were separated. The XML format for V5.1 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 V5.1 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.

 

Portal settings

The portal settings contained in the global-settings and services-settings XML elements are significantly different between WebSphere Portal V4 and V5.1. If you have XML scripts from WebSphere Portal V4 which modify these settings and you want to migrate these XML scripts for use in V5.1, insert the appropriate key names and values for V5.1 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 V5.1 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. For more information on lookup of portal resources refer to the XML reference. In WebSphere Portal V5.1 you can identify a resource uniquely by specifying its object ID.

You can now export and update 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 V4.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 V4.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 V4, access rights on resources were specified by access-right sub-elements of the resource. Access control in WebSphere Portal V5.1 is conceptually different from V4. 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 V5.1, 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 V5.1.

The resources that support access control definitions in XML have changed from WebSphere Portal V4 to V5.1:

  • Access control cannot be specified any more on skins and themes in WebSphere Portal V5.1.
  • Access control can now be specified on the following resources that did not support access control in WebSphere Portal V4:
  • Access control can be specified on the following new resources:

In WebSphere Portal V4, 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 V5.1, 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:

  • The package tag has been renamed to web-app.
  • The application tag has been renamed to portlet-app.
  • The portlettemplate tag has been renamed to servlet.
  • The globalid attribute has been renamed to uid.

 

Page definitions

The representation of the page hierarchy structure has changed significantly between WebSphere Portal V4 and V5.1. 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 WebSphere Portal V4.x to V5.0

 

Changes from both Versions of WebSphere Portal, 4.1 and 4.2 to V5.0

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 V4.1 to V5.0

In WebSphere Portal V4.1 the portal navigation structure was expressed as pagegroup XML elements referring to the contained pages. In V5.1, 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:

  • H (horizontal) for rows
  • V (vertical) for columns.

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

 

Changes from WebSphere Portal V4.2 to V5.0

New portal navigation structure: In V4.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 V5.1, 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 subelements url, supported-markups, and localedata
  • The attributes compositionref, themeref, and allmarkupsallowed.

The component type unlayered has been renamed to container.

Remote Portlet Web Services (RPWS): WebSphere Portal V5.0 and V5.1 does not support the IBM proprietary Remote Portlet Web Services (RPWS) that WebSphere Portal V4.x supported. (This is not the same as WSRP - Web Services for Remote Portlets.) The corresponding XML elements and attributes have been removed from the XML syntax:

  • The proxy-portlettemplate and uddi-registry elements
  • The remote and published attributes of portlets and Web modules (package tags in V4).

 

See also

Home |

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.