About the XML configuration interface

 

 

What is the XML configuration interface?

The XML configuration interface provides a batch processing interface for portal configuration updates. It allows you to export an entire portal configuration or parts of a configuration, for example specific pages, to an XML file. You can then re-create the exported configuration from such a file on another portal.

You access the XML configuration interface using a command line tool. This command line client is a small separate program that connects to the server using a HTTP connection. It is therefore possible to configure the portal remotely.

 

Tasks that you can perform with the XML configuration interface

These are typical tasks for which you use the XML configuration interface:

Use of the XML configuration interface for backing up or restoring complete portal configurations is restricted by the following limitations:

  1. A complete XML export of a portal configuration is not sufficient to re-create the portal. You also need the WAR files for your portlets and possibly additional file resources, such as theme files if they are not part of the standard portal installation.

  2. The XML configuration interface is not designed to deal efficiently with large volumes of data. For a backup and restore solution on a production server, rely on low-level database and file system backups.

 

Access and security considerations

To be able to use the XML configuration interface, you need to have the manager role on the virtual resource XML_ACCESS and the administrator role on the virtual resource PORTAL. This implies that be a super administrator of the portal, who can perform any action. Consequently, there are no further access control checks that could restrict your actions when you use the XML configuration interface; you may view all resources in the portal and you may update and delete all resources.

When you run the XML command line tool, authenticate yourself by specifying your portal user ID and password. Note that the user and password are sent to the server unencrypted, therefore only connect to the XML configuration interface from inside a protected intranet where you can be sure that the HTTP connection is not compromised.

 

Overall structure of the XML input and output

There are two types of requests that can be sent to the XML configuration interface:

Export requests

An export request triggers the export of complete or partial portal configurations into XML. It does not modify the configuration of the portal. It results in a response file.

Update requests

An update request modifies the configuration of the portal according to the values found in the XML script.

Requests to and responses from the XML configuration interface use the same XML format. An export request generates an XML response that contains all the configuration data required to re-create the exported configuration part. This means that you can export a portal configuration, save the XML output file and, without modification, send it to another portal to re-create the same configuration there.

You can find the XML schema for the XML format that use for reference in the file PORTAL_DIR/doc/xml-samples/PortalConfig_1.2.xsd. An XML request contains the following:

 

Representation of a portal configuration in XML

The XML hierarchy that is found under the portal section in the XML request file represents the structure of a portal as an XML tree. This tree contains resources in the portal, such as portlets or pages, and their configuration data. The XML hierarchy of all supported portal resources is shown in the following table:

XML element Description 
portal
 Main element of every XML request
    global-settings
 Global portal settings
    services-settings
 Global portal settings for portal services
    virtual-resource
 Virtual resources that have associated access control settings
    user
 Users defined in the portal user management system
    group
 Groups defined in the portal user management system 
    markup
 Markups that can be supported by portal pages 
    client
 Client devices (browsers) that the portal knows about 
    event-handler
 Definitions of event handlers that can react to events in the portal 
    skin
 Visual appearance settings that can be applied to user interface elements 
    theme
 General visual settings that can be applied to the user interface 
    web-app
 Web modules containing portlets 
       servlet
 Servlets that are defined in the Web module 
       portlet-app
 Portlet applications that are defined in the Web module 
          portlet
 Portlets that are defined in the portlet application 
    content-node
 Elements of the portal content tree (pages or labels) 
       component
 Layout components of pages 
          portletinstance
 Occurences of a portlet on a page with customized settings 
    credential-segment
 Segments for storing credentials in the credential vault 
       credential-slot
 Slots in a credential segment that hold a credential 
    url-mapping-context
 User defined URLs that map to pages in the portal

Depending on the content of an XML request, these resources can be created, modified, deleted or exported. An XML request can contain any number of such resource definitions. It can therefore create hundreds of new resources in one step or modify only a single configuration setting of one existing resource.

See also