XML configuration reference

XML configuration reference

Overview
Types of portal resources
request
portal
task
name
action
user
web-app
content-node
component
Special configuration data entries
Actions on portal resources
locate
create
update
export
Syntactic restrictions on the input syntax
Object IDs in XML scripts
Symbolic object IDs and ID generating mode
Lookup of portal resources
Export sets of resources
Mandatory and optional attributes
Page layout modifications
Marking pages as hidden under the content root
Import WAR files
View update of changes
Transactionality
Error recovery
Hints and tips

Overview

The top level structure of an XML request or response...
<?xml version="1.0" 
      encoding="UTF-8"?>

   <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:noNamespaceSchemaLocation="PortalConfig_7.0.0.xsd"
            type="export|update"> 

      <portal ... >
          definition of configuration parts to be exported or updated
      </portal>

      <status ... >
          success or failure indication for the processing
      </status>
</request>
The type attribute indicates whether the XML request contains specifications for exporting or for updating portal resources.
The portal section describes the parts of the portal configuration that should be exported or updated.
The status section is optional; in an XML response it indicates success or failure of the requested operation. If a status element is present in a XML request, the server simply ignores it.
The main request element specifies the XML schema used by xmlaccess.sh. Always use the schema reference that is shown in the example, that is a reference with no namespace to the schema...
com/ibm/wps/command/xml/PortalConfig_7.0.0.xsd

You can verify syntax against this schema using a suitable editor or parser. The schema also contains annotations that give detailed information on the meaning and possible values of all configuration entries.
XML sample files are located in...
$PORTAL_HOME/doc/xml-samples

For example, to export the entire portal configuration, save the following to file exportall.xml...
   
<?xml version="1.0" 
      encoding="UTF-8"?>

      <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:noNamespaceSchemaLocation="PortalConfig_7.0.0.xsd"
               type="export"> 

         <portal action="export"/>

   </request>
.and then run...
xmlaccess.sh -user user_ID  \
             -password password  \
             -url myhost:10039/wps/config  \
             -in exportall.xml  \
             -out exportall_result.xml 
You can look at the contents of the response to see how the configuration of individual portal resources, such as portlets or pages, is represented in XML elements and attributes.
Additional to the export and update request types, a third request type...
export-orphaned-data

.is available for the special scenario of deleting of orphaned data.
The wp.xml.jar is located in...
$PORTAL_HOME/base/wp.xml/shared/app/wp.xml.jar

Types of portal resources
Portal resources are represented by the following XML tags:
request The main tag of every XML request. This element must always appear exactly once and must enclose the request. You can use this attribute to export release data from the portal database to later feed that data it into the staging process.
portal The main element of every XML request. This element must always appear exactly once and supports only locate and export actions.
global-settings
services-settings Settings for global portlet configuration values and for specific portal services. These elements support only locate and export actions.
IBM recommends leaving the XML scripts for exporting and updating these settings unchanged. Do not manually change the values in the XML scripts, as this might result in invalid portal configurations. To modify these settings, use the appropriate administration portlets instead after the XML update of a configuration.
language This tag allows you to add languages to the list of supported languages defined in the portal or to delete languages from that list. For bidirectional languages use...
bidi="true"

task Schedules the cleanup of portal resources, the cleanup of composite applications, the monitoring of policies for composite applications, and the administration of federated tags. Cleanup refers to the deletion of portal pages and all page-dependent resources that have been marked for deletion. Specify one or more tasks to be run immediately or at specified intervals. The scheduling interval parameters dayOfMonth and dayOfWeek are optional and are mutually exclusive. Each scheduling interval parameter requires a value for the parameter startTime. To run a task daily, use only the parameter startTime.
name

com.ibm.portal.datastore.task.ResourceCleanup Clean up portal resources. If specified without a scheduling interval parameter, portal resource cleanup is performed immediately when you run the XML script.
com.ibm.portal.ai.task.AITask_Purger Clean up composite applications. If you specify this task without a scheduling interval parameter, composite application cleanup is performed immediately when you run the XML script.
In contrast to the task that cleans up portal resources, com.ibm.portal.datastore.task.ResourceCleanup, composite application tasks can be scheduled to run more than once. For example, you can schedule an application task to run every Monday at 10.00 a.m. and every Friday at 1:00 p.m. To accomplish this, simply add the task instance ID to the task ID. For more information, see the topic Automated tasks for composite applications.
com.ibm.portal.ai.task.AITask_PolicyHandler Monitor policy settings for composite applications. If you specify this task without a scheduling interval parameter, the monitoring of policy settings for composite applications is performed immediately when you run the XML script.
In contrast to the task that cleans up portal resources, com.ibm.portal.datastore.task.ResourceCleanup, composite application tasks can be scheduled to run more than once. For example, you can schedule an application task to run every Monday at 10.00 a.m. and every Friday at 1:00 p.m. To accomplish this, simply add the task instance ID to the task ID. For more information, see the topic Automated tasks for composite applications.
com.ibm.portal.cp.SynchronizationTask Synchronize collaborative data including tag categorization information provided by Web Content Manager tagging. If you specify this task without a scheduling interval parameter, the portal performs a resource cleanup immediately when you run the XML script.
com.ibm.portal.services.RefreshIWidgetDefinitionsTask Refresh iWidget definitions stored in WebSphere Portal. Refreshing iWidget definitions refers to re-loading the iWidget definition XML files and updating the corresponding iWidget Wrapper portlet clones accordingly.
To call this task directly run the following configuration task: refresh-iwidgets-definitions. See the Task refresh-iwidget-definitions topic for instructions.
dayOfMonth The task to run monthly, specify a number from 1 to 31. If the number you specify is higher than the last day of the month, the cleanup is performed on the last day of the month. For example, specifying a value of 31 sets the task to run on January 31, the last day of February, March 31, April 30, and so on.
dayOfWeek The task to run weekly, specify a number from 1 to 7, where 1 is equivalent to Monday and 7 is equivalent to Sunday.
startTime If you specified a scheduling interval of dayOfMonth or dayOfWeek, specify the time of day at which you want the task to start. Use the format HH:MM to specify a value from 0:00 to 23:59. You do not need to include leading zeros, for example 4:45. To run the task daily, use this parameter only; do not use the parameters dayOfMonth or dayOfWeek.

The Task.xml sample shows you how to schedule the cleanup of portal resources and composite applications and the monitoring of policies for composite applications.
If you delete a page with an object ID and then use xmlaccess.sh to re-create the same page with the same object ID, you might receive an error message indicating the operation was canceled because these actions created a duplicate key value.
When you run a cleanup task, xmlaccess.sh only schedules the task to be run in IBM WebSphere Application Server. This does not necessarily mean that WAS runs the task immediately. To determine when a task has started and ended, check the portal log SystemOut.log for the EJPDE0002I and JPDE0003I messages. These messages confirm that the task has successfully completed. After you have confirmed this, you can run the XML script for re-creating a page with the same object ID that it had before the deletion.
action Define the required action.
virtual-resource These are resources that only have access control definitions attached, but are not otherwise represented in the portal. The virtual resource PORTLET_APPLICATIONS, for example, allows you to give users access to all installed portlets, but does not correspond to an actual portlet. The virtual resource element supports only update and export actions.
user
Users in the portal user repository. The definitions include their properties, for example the user's preferred language, and portal access control settings that apply to users, for example, who is allowed to administer them. xmlaccess.sh allows setting the password for a user, but it does not export the password. The password attribute is required for creating new users. Therefore you cannot directly use the response file from an XML export request to create new users; you need to add a password attribute to the XML first.
You can either specify the name attribute of users and groups with a full DN (distinguished name) as in uid=wpsadmin,cn=users,... , or with a short ID as it is used for portal login, for example wpsadmin. An XML response file from a portal export request always contains full DNs.
With regards to the user tag there are two special cases for which you have to specify particular attributes, depending on the task you want to perform:

Export users and groups
Deregister users and groups from the portal.

A full portal export does not normally include user and group information, but only if you explicitly specify in XML request that the user is to be exported. To export all user and group information, set the export-users flag on the main request tag to true as follows:
<request ... export-users="true" ...>
To export groups without the members, set the export-users flag to no-member.
Search for users or groups is a time consuming task. A search might time out or return more results than the system can handle or the user might expect. To prevent this behavior, you can limit searches for users or groups by setting a timeout or a maximum number of search results.
The values of some attributes of the tag user correspond to settings in included parameter tags. If you include both in export request, but specify different values for them, then the value set by the parameter tag overwrites the value set by the attribute, and is exported as the attribute. The values of the attributes of the user tag correspond to the included parameter tags as follows:

Attribute parameter tag with name=" " Comments
firstname givenName

lastname sn

name uid Mandatory for LDAP atttribute.

You can define the first name of a user at creation by using either the attribute firstname or the parameter tag with the givenName attribute. If you use both and specify two different names, then the value specified by givenName is exported as the attribute firstname. Example XML export request:
<?xml version="1.0" encoding="UTF-8"?>


<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:noNamespaceSchemaLocation="PortalConfig_7.0.0.xsd" 
         type="update" 
         create-oids="true">

     <portal action="locate">

         <user action="update" 
               firstname="John_1" 
               password="password" 
               lastname="Miller" 
               name="John's name">

             <description>John Miller</description>

             <parameter name="cn" 
                        type="string" 
                        update="set">John Miller</parameter> 
             <parameter name="givenName" 
                        type="string" 
                        update="set">John_2</parameter>

         </user>

     </portal>

</request>
This request sets the value John_2 for the firstname attribute.
On some LDAP servers, where the cn is part of the distinguished name, you may not be able to update the cn.
Deregister users and groups from the portal: If portal users or groups have been removed from the user registry, but not from the portal database, or if users have been muted, for example after too many wrong password attempts, you can export these users and groups for later removal by using the cleanup-users attribute with the request tag. To export these users and groups, set the cleanup-users flag on the main request tag to true as follows:
      <request ... cleanup-users="true" ...gt;
If you set this property to true, all users and groups that no longer exist in the configured user repository, such as LDAP, are exported with their action set to delete. You also need to set the export-users attribute to true.
Before re-importing the file, you need to review and edit the result file and remove all users and groups that you want to keep in the portal database. During XML import all users and groups that remain listed in the file will be removed from the portal database.
After deleting these entries via the modified XML script, all customization is lost for the deleted users and groups.
The CleanupUsers.xml sample XML file is an example for exporting users and groups.
group Groups in the portal user database. The definitions include portal access control settings and membership information, for example, which users belong to the group. See under user just above for more information on how to handle groups in XML.
markup Definition of markup types that the portal pages support.
client Definition of client devices, how they are detected, and which markups and features they support.
event-handler Definition of programming code inside the portal that should be notified when certain events occur in the portal, for example, when a page is created. Describes the name of the Java class and the events that should be reported.
skin Describes the visual appearance, for example, the border of individual user interface elements, for example, of portlets on a page. Skins can be assigned to content nodes and components.
theme Describes basic properties, for example, colors and font type, of the appearance of an entire group of pages. Themes might restrict the selection of possible skins on the associated pages. Themes can be assigned to content nodes.
scoped-skin The tag is used inside a theme section. It defines a skin that is in the scope of the theme of that section. This means that this scoped skin is owned and used exclusively by the theme section in which the scoped-skin is defined.
wsrp-producer This is the Producer definition on the Consumer side for Web Services for Remote Portlets (WSRP). It allows an administrator to consume and integrate remote portlets that are provided by the WSRP Producer.
After you have integrated a WSRP service, the portal handles it like a regular local portlet. For example, you can add the portlet to pages.
web-app
Web modules which correspond to a deployed WAR file. To use the portal, one or more (concrete) portlet applications must be defined that describe specific settings. In a portlet.xml deployment descriptor, this element corresponds to the portlet-app tag.
Web modules for standard API compliant portlets can contain only one single portlet application, whereas web modules for IBM API compliant portlets can contain more than one portlet application. For IBM API portlets, the uid attribute must match theuid attribute defined in the deployment descriptor.
IBM API portlets are deprecated in 7.0 but are still supported.
For standard portlets, the uid attribute must be constructed by the id attribute of the portlet-app subelement and a .webmod suffix or, if the id attribute is not specified, the WAR filename and a .webmod suffix. Example:
    <web-app action="update" active="true" removable="true" uid="jsr_bookmarks_id001a.webmod"> 
         .....
    <portlet-app action="update" active="true" uid="jsr_bookmarks_id001a">	  
Depending on the path location of WAR files, previously exported WAR files might not be found during an XML import due to incorrect path information. For information about how to use the <url> subtag with the <web-app> tag refer to Import WAR files.
servlet Servlets are defined in the web module and created as part of the WAR file deployment. They cannot be created or deleted explicitly. Create and delete actions are not supported. In a standard portlet.xml deployment descriptor, this element corresponds to the portlet tag. In an IBM portlet.xml, there is one servlet created for each concrete-portlet tag.
portlet-app Portlet applications that are contained in a web module and contain specific settings. Usually, applications and their contained portlets are defined in the WAR file of the web module and are created by the portal during deployment. For IBM API compliant portlets, this element corresponds to the concrete-portlet-app tag of the portlet deployment descriptor.
For standard compliant portlets, the uid attribute must match the id attribute of the portlet-app element that is defined in the deployment descriptor. If the id attribute is not set in the deployment descriptor, specify the WAR file name.

When the application is used in a WSRP context, the portlets that are contained in the application are defined remotely and can be integrated by using xmlaccess.sh. In this case portlet applications need to define a groupid attribute.
After you have deployed a WAR file locally or integrated a WAR file as a WSRP service, you can also create additional portlet applications (and the contained portlets) with different settings. This is also known as copying or cloning the portlet application.

portlet Portlets that can be placed on a page and contain specific settings. Normally, portlets are defined in the WAR file of the web module and are created by the portal during deployment. When the portlets that are contained in the web module are used in a WSRP context, they are defined remotely and are integrated by xmlaccess.sh. In this case portlet applications need to define a handle attribute. A new flag, provided , has been introduced for providing portlets for remote invocation and withdrawing them.
When you create a new portlet in an additional application, it must refer to one of the servlets that was defined in the web module. In a portlet.xml deployment descriptor, this element corresponds to the concrete-portlet tag.
If you write standard API compliant portlets, not use the parameter tag to add parameters; use the preferences tag instead.

content-node An element in the content hierarchy of the portal. The portal supports several types of content nodes:

A page is a content node that is made up of nested layout elements and displays portlets.
A label is a content node that serves for organizing the content hierarchy but does not display portlets.
A static page is a content node that contains a static HTML file or an HTML fragment.
An internal URL is a content node that points to other portal content by referencing a URL.
An external URL is a content node that points to a web page outside the portal.

All content nodes in the portal are organized in a hierarchy; at the root of this hierarchy is the special content node wps.content.root. A content node of the type page can be derived from another parent content node so that it partially overrides or extends the layout of its parent. While the portal and the portlet for Working with pages always display an aggregation of a composition layer and all of its ancestors, xmlaccess.sh must manage every layer separately.
It is recommended to always export and replace an entire stack of page layers and not to use XML requests to modify individual layout components or derived page layers. In particular, do not try to manually create XML scripts for the definition of derived pages, as the reference structure is quite complex. Instead, use the portlet for Working with pages to edit page layouts, and then export the result into an XML response file.
component A layout component inside a page. The portal supports two types of components:

A container is a row or column container that aggregates child containers.
A control component contains a portlet instance.

If you update an existing page with an XML script and the script specifies components inside that page, the layout-processing attribute of that page defines how those new components interact with the existing layout of the page.

portletinstance An individual occurrence of a portlet on a page. The portlet instance includes the user-defined portlet data that was set using the edit mode of the portlet.
A portlet instance is always contained in a component of type control; deleting a portlet instance automatically deletes the component in which the portlet was contained.
Instances of standard portlet API compliant portlets must not use the parameter tag to add parameters; they must use the preferences tag instead.
For personalized content, where only portlet parameters but no page structure is changed, use the following attributes with the portletinstance tag:

owner Define the owner of the portletinstance.
parentref Define the parent of the portletinstance.

cross-page-wire Represents a property broker wiring between two portlet instances on either the same page or on different pages. A wire connects a source and a target portlet instance so that values which change in the source are propagated to the target. This tag has the source-pageref and target-pageref as the only additional attributes to the wire tag. When you export a page that has cross-page wires connected, then the cross-page-wire tag is exported, even if there is no direct reference to or from the page or the wire.
A wire can be created only if the wiring endpoints of the corresponding portlets exist. Legacy portlets that are not compliant with JSR 168 or 286 might create those endpoints programmatically on their first rendering. Therefore, xmlaccess.sh cannot create a new wire for those portlets unless they have been rendered the first time. To create this wire, first view the page that contains the portlet with a web browser and then create the wire by using xmlaccess.sh.

wire Represents a property broker wiring between two portlet instances on a page. A wire connects a source and a target portlet instance, so that values which change in the source are propagated to the target.
The wire tag is deprecated with WebSphere Portal v7.0, as it supports property broker wiring between two portlets on the same page only. Use the cross-page-wire tag as it supports property broker wiring between portlets on the same page and on different pages.
A wire can be created only if the wiring endpoints of the corresponding portlets exist. Legacy portlets that are not compliant with JSR 168 or 286 might create those endpoints programmatically on their first rendering. Therefore, xmlaccess.sh cannot create a new wire for those portlets unless they have been rendered the first time. To create this wire, first view the page that contains the portlet with a web browser and then create the wire by using xmlaccess.sh.
credential-segment Groups a collection of credential entries for a specific back end credential store (vault). The configuration of credential segments cannot be modified after they have been created.
credential-slot A single credential entry that describes information required to connect to a protected resource outside the portal. xmlaccess.sh covers only the definition of the credential slot. The actual credential, for example the password for an application, is stored in the back end credential store. It can be set or updated, but not exported by using xmlaccess.sh.
To set user credentials use...
xmlaccess.sh UpdateVault.xml

url-mapping-context Define arbitrary URL spaces that map to portal content.
user-resources Perform export or delete actions for specific users.
policy-node Define arbitrary URL spaces that map to portal content. When you use xmlaccess.sh to work with policies, some limitations apply.
application-role Define a compound role that combines multiple authorization roles and is specific for a set of users.
The following tags and attributes are for portal internal use only. If you encounter these tags or attributes in an XML export script to use for later update, do not change these tags or their content in any way.

action-set For portal internal use only.
category For portal internal use only.
composite-app For portal internal use only.
federation-server For portal internal use only.
protected-resource For portal internal use only.
resource-type For portal internal use only.
transformation For portal internal use only.
transformation-app For portal internal use only.
transformationinstance For portal internal use only.
serverref This is a tag attribute for the content-node tag; it is for portal internal use only.
content For portal internal use only.
supported-processing-event For portal internal use only.
supported-publishing-event For portal internal use only.
qname For portal internal use only.
alias For portal internal use only.
class-name For portal internal use only.

The following tags are available for portal resources for tagging and rating: tag, rating, custom-resource, and category-instance. For more detailed information about these tags refer to the topic about Using xmlaccess.sh to administer tags and ratings.
Note that xmlaccess.sh only manages resources of the portal core and not those of additional components, such as Portal Personalization.

Special configuration data entries
Additional to the tags representing portal resources as listed above, XML provides the following tags or attributes for special purposes:
localedata Describes locale specific data associated with portal resources. The localedata element allows a number of child elements (title, description and keywords), but not all of them are supported for all portal resources. Unsupported child elements are ignored. The charset attribute is only used in markup elements.
When you create XML files that contain lots of translated texts in different languages, it is sometimes more convenient to specify those texts in properties files instead of including them in the XML script. Therefore you can alternatively use a URL to specify a properties file. XML will then read the title, description, and keyword texts from that file.
parameter Describes name-value pairs associated with portal resources. The parameter element supports a type attribute, but for all elements except portlet instances, the type must be string. Portlet instances additionally support the binary type which treats the parameter contents as Base 64 encoded binary data. User definitions support setting multiple values for the same parameter name. With all other resources, setting a parameter overwrites any previous value stored under the same parameter name.
If the WSRP Producer requires a registration of the WSRP Consumer with certain registration properties, specify these properties as parameters.

preferences This is a derivation from the name/value pair. It relates to the parameter element. It describes name/multivalue combinations, that is, combinations of a name and one or more value child elements that are associated with the portal resources wsrp-producer, portlet, and portlet-instance.
The value elements support only string type attributes, no binary type attributes.
Set a preferences value overwrites all values that were previously stored under the same preferences name.
portlet and portlet-instance can only have the preferences element if they comply with the standard portlet API. For all other portlets, use the parameter element.
If the WSRP Producer requires a registration of the WSRP Consumer with certain registration properties, specify these properties with the parameter tag. Optionally, you can use the preferences element to define which user attributes you want to have transferred in the WSRP communication with the Producer. These user attributes are the user attributes defined in LDAP.

access-control Describes the access permissions associated with portal resources. By specifying access-control subsections for resources in the XML, you can, for example, define which users or groups are allowed to manage a resource. The access control definition for a resource includes all of the following information:

The owner of the resource
The roles defined on that resource
The mapping of users or groups to a role
Whether inheritance of a role or from the parent resource or to child resources is blocked.

Alternatively, a resource can be a private resource of a specific owner, or it can be managed externally.
When you specify users or groups in the access-control section of a resource, you can either use the full DN as in...
uid=wpsadmin,cn=users

.the short ID as it is used for portal login, for example wpsadmin. An XML response file from a portal export request always contains full DNs.
When you change the access control state of a resource from public to private or vice versa, this also affects all the resources that inherit access control from this resource. You can never have a public resource that inherits access control from a private resource.
objectid Almost all resources in the portal have an object ID, which identifies the resource. The object ID allows addressing the resource unambiguously. It is also used to express references from one resource to another. For example, when a theme is assigned to a page, the configuration of the page includes the object ID of the theme. See the Object IDs in XML scripts section on object ID handling in XML scripts for more information.
uniquename
A resource that has an object ID can optionally also have a unique name. The unique name can then also be used to identify the resource unambiguously, because a unique name can be used only once in a portal installation.
If you execute an XML update that assigns a unique name which is already used on the system, the execution will fail. You can delete the unique name for a resource by setting it to the value undefined. When you create unique names in XML scripts that you run on many different portal installations, for example to install add-on portlets and pages, you should use a specific prefix for any unique names that you assign, to minimize the chances that they clash with existing unique names on the system. For example, the prefix wps. is used for all unique names that are created as part of the portal installation.

When you create a nested element, for example a component, with a uniquename attribute, the whole hierarchy upward from that element must also have uniquename attributes. Example XML export request snippet:
     <content-node ...
          <component uniquename="component_1"...
               <component uniquename"component_2"...
                    <component uniquename"component_3"...
                         .....
                    </component>
               </component>
          </component>                       
     </content-node>
Failing to do so might result in the following error message:
        XMLC0142E: Unique name unique_name is already used in the portal.
ordinal The client and component resources take an ordinal attribute which represents the sorting order. (In the case of client resources, if more than one client entry matches a connecting device, the entry with the higher ordinal takes precedence.)
When ordinals for resources are set in an XML script, you have the following options for specifying them:

As a plain integer value. In this case, the value is written to the database. The resource is sorted into the position that this ordinal value has relative to the ordinals of existing siblings. For example, if you create a new page with ordinal="350" under an existing label, and there are already other pages under that label with the ordinals 100, 300 and 500, the new created page will appear in the third position. If you specify an ordinal which has already been assigned to an existing resource, the order of the two resources cannot be predicted.

As a position indicator. Specify with a hash mark ( # ), followed by an integer value. In this case the resource is inserted in the sequence of resources at the position indicated by the specified value. For example, when you create a new page with ordinal="#2", it appears in the second position in its content parent.

The special values first and last. In this case, a value is chosen so that the resource is sorted at the first or last position in its content parent.

An XML export response file always contains the literal ordinal values as they are stored in the portal database. Note that specifying a position indicator or special value will not necessarily produce the required effect if you are working with derived pages, because in these cases the order of elements depends on the individual user viewing the portal.
domain Use this attribute to specify in which database domain a specific resource should be stored. You can also use the domain attribute to export release data from the portal database by specifying domain="rel" to later feed that data it into the staging process. Use one of the following values with the domain attribute:
rel Export only the release data.
cust Export the release data with the customization data. This includes all referenced release data as locate statements.
Export composite applications is not supported. To export composite applications use the back up and restore feature.
export-release This attribute is for use with the request tag. Do not use this attribute any more. Instead, use the domain attribute (above) by specifying domain="rel".
The following two attributes have been added for the portletinstance tag. Use them for personalized content, where only portlet parameters are changed, but not the page structure.
owner Define the owner of the portletinstance.
parentref Define the parent of the portletinstance.
You can find additional information on the meaning and possible values for configuration elements and attributes in the schema annotations.

Actions on portal resources

All XML elements that represent portal resources have a required action attribute. The action attribute of XML elements determines what type of processing is applied to the portal resources. The following actions are allowed:

Action Resulting processing
locate Identify the portal resource corresponding to this XML element (usually required as a context for other actions).
create Create a new portal resource with the given attributes. A new resource is always created, even if another resource with the given name already exists.
update Update the configuration of the corresponding portal resource with the given configuration data (attributes and dependent configuration data elements); if no corresponding portal resource can be found, it is created.
delete Delete the portal resource corresponding to this XML element.
export Include an XML representation of the portal resource corresponding to this element in the output of the XML command.

Example: the following XML snippet sets the portlet "MySpecialPortlet" to inactive status:
     <portlet name='MySpecialPortlet' action='update' active='false'/>
Syntactic restrictions on the input syntax
There are certain restrictions on the allowed values for the action attribute:

If the request type was specified as update, only the actions locate, create, update and delete are permitted.

If the request type has been specified as export, only the actions locate and export are permitted.

Create actions (and update actions for non-existing elements) might require that certain attributes of the element are defined that are not required for other update or delete actions.

Actions of nested elements must not be contradictory. If you choose to delete a resource, you cannot create any other resources inside it. The following table lists all commands, together with the allowed commands for subelements:

Action Allowed actions in subelements
locate locate, create, update, delete, export
create locate, create, update
update locate, create
delete no subelements allowed
export no subelements allowed

Two or more XML elements might correspond to the same portal resource. For example, it is possible to have one element that creates a portal resource and another that updates the same resource with new configuration data.
Configuration data elements do not have an associated action, but most of them have an update attribute that determines the type of update that is applied. The following values are possible:

update Resulting processing
set The corresponding configuration data (for example, parameter) is set, or, if it does not yet exist, it is created.
remove The corresponding configuration data (for example, parameter) is removed

Note that configuration data elements are processed only if their parent has an update action. For example, the following fragment will not update the capability information for the given page:
   <client uniquename="smart.browser" action= "locate">
        <client-capability update="set">HTML_JAVASCRIPT</client-capability>
   </client>
All specified actions are processed in the textual order in which they are specified in the XML input (document order). If there are any interdependencies between the actions, the user (or program) providing the XML input is responsible for ordering the elements correctly.

Object IDs in XML scripts
All resources in the portal (except for the portal and the settings resources) have an object ID that uniquely identifies them in the portal. That ID is generated by the portal when the resource is created. These object IDs are represented by the objectid attributes in an XML export.
References between resources are represented by these object IDs: One resource has a reference attribute that contains the object ID of another resource. For example, a portlet instance that is to be displayed on a page must reference a portlet. Therefore the portletinstance tag has a portletref attribute that corresponds to the objectid attribute of the portlet. Consequently, you see the following snippets in an XML export:
<portlet action="update" ... objectid="3_G0Q03FH200A5202QRHAG4320G0" ... >
      ...
<portletinstance action="update" ... portletref="3_G0Q03FH200A5202QRHAG4320G0" ... >
All resources get an object ID assigned in the portal when they are created. That object ID can not be altered later. When you create new resources in the portal administrative user interface, they automatically get a new object ID generated by the portal. When you create a new resource with XML, it also always gets a new object ID, if you do not specify one in the XML. Note that you can not simply "invent" object IDs for new resources, because they must conform to a correct internal representation. The only way to get valid object IDs is from an XML export.
In XML scripts the objectid attribute of a resource is used for the following purposes:

To look up the resource, if the action is locate, export, update or delete.
To set the object ID for a new resource, if the action is create.
To set the object ID for a new resource, if the action is update and no resource with that object ID exists.
To describe links from one resource to another.

You can use object IDs to uniquely specify resources that you want to administer. For example, the following snippet deletes a specific known page. (You would normally get the object ID of the page from an XML export.)
   <content-node action="delete" objectid="6_G0Q03FH200A5202QRHAG4320O0"/>
The following snippet looks up a page with a specific object ID. If it cannot find the object ID, it creates it. If it already exists, it updates it.
   <content-node action="update" 
        objectid="6_G0Q03FH200A5202QRHAG4320O0" 
        type="page" 
    ... >
The next snippet creates or updates a theme with a specific object ID and then assigns that theme to a label:
   
        <theme action="update" 
               objectid="J_G0Q03FH200A5202QRHAG4320S1" ...>
            ...
        <content-node action="update" 
          objectid="6_G0Q03FH200A5202QRHAG4320O0" 
          type="label" themeref="J_G0Q03FH200A5202QRHAG4320S1" ... >
If the theme already exists with the specified object ID, you can directly use that object ID in references without having to include the theme in the XML script. The next snippet assumes that the theme has already been created. For example, it might have been copied from another server in a previous step. Therefore the snippet only assigns the theme to the label:
   
        <content-node action="update" objectid="_6_609EVJDBI1S5CD0I_C3" 
             type="label" themeref="J_G0Q03FH200A5202QRHAG4320S1" ... >
In this case, the theme is looked up in the portal data store using its object ID J_G0Q03FH200A5202QRHAG4320S1. If no theme with that object ID is defined in the portal, you get an error during the XML validation.
An object ID is globally unique. Two object IDs that were automatically generated by different portal installations can never be the same. Therefore you can exchange resources between different portal installations using XML export and update requests without having to worry about possible object ID conflicts. The only way that you can ever duplicate an object ID is by transferring a resource (including the object ID) to another portal with an XML export and update.
In many cases, this is the required behavior. However, if you do not want to copy the same resource to another portal, but you want to create a new resource instead, regardless of existing OIDs and without any chance of causing conflicts, either use symbolic object IDs or delete the objectid attribute from the XML script. In the latter case the portal creates a new object ID.

Symbolic object IDs and ID generating mode
In some cases, you might need to use objectid attributes to express references between resources in XML script, but you do not want these to be read from or written to the portal database. In this case, the object ID would be only a symbolic reference inside the XML script. For example, you might want to create a new theme and page, and reference the theme in the page. Nevertheless you want to let the portal chose an object ID for it because you do not want to accidentally overwrite an existing resource.
There are two ways to achieve this:
You can switch the XML processing to ID generating mode by setting the create-oids flag on the main request tag:
    <request ...  create-oids="true" ... >
In this mode, all object IDs are not written to or read from the portal database. Instead, their only purpose is to express the linking between resources in the XML. When the XML processing creates new resources, they are created with a new system generated object ID, not with the object ID specified in the XML.
You can use a value for an objectid attribute that cannot be decoded as an object ID, such as a simple string name, the XML processing treats it as symbolic and does not try to use it for looking up the object or write it to the database. This makes it possible to selectively treat individual object IDs as symbolic.
Note that even in symbolic object IDs, anything after the first space is not significant for processing. For example, you could use the following snippet to create a portlet and put it on a page using a symbolic object ID:
   <portlet action="update" ... objectid="Welcome_Portlet" ... >
       ...
   <portletinstance action="update" ... portletref="Welcome_Portlet" ... >
As the object ID values are purely symbolic, you cannot use them in a reference without first "defining" them in the same XML script. Before you can use the portletref="Welcome_Portlet" attribute specification in an XML update, also have a portlet with objectid="Welcome_Portlet" defined in the same XML; otherwise a syntax error is reported.
Of course, the object IDs in the XML are also not used for looking up a resource. To refer to existing resource, you need to use a unique name (see below) instead. In ID generating mode, the following snippet locates an existing portlet by its name, "defines" a symbolic object ID for it and places the portlet on a page:
   <portlet action="locate" name="Welcome Portlet" objectid="Welcome_Portlet">
        ...
   <portletinstance action="update" ... portletref="Welcome_Portlet" ... >
As object IDs are not used to identify existing resources in ID generating mode, it is good practice to define unique names for all resources that are created in such scripts. That way, if the script is executed twice, the second execution can find and update the resource by its unique name, instead of creating two identical resources.
When you create resources using symbolic object IDs, it can sometimes be useful to know the actual object IDs of the new resources. You can set the export-mapping flag on the main request attribute to obtain this information:
     <request ...export-mapping="true" ... >  
When you set this flag, a mapping section is appended to the XML response. For every symbolic object ID given in the input, this mapping shows the actual object ID in the portal data store.
The ID generating mode is useful if you want to create an XML script that installs a group of new resources and is executed on many different portal installations. This can be, for example, a part of the installation procedure of a portal add-on that you give out to other parties. In this case, you have no control over the systems on which the XML script is executed, and it is of no interest to you which object IDs the resources actually get.
Use the ID generating mode for all the examples under Working with xmlaccess.sh, because they should work on any portal installation.
The identity of the objects that are configured in the XML script is expressed by their object ID. Therefore you should use "real" object IDs in scripts, when you want the objects in XML to retain their identity. For example, when you use an XML export request and the resulting response file to copy a resource from a staging to a production system, the resource is created on the production system with the same object ID as on the staging system. This way you can establish a correspondence between the two resources. When you later transfer the same resource again, the XML processing looks up the resource by its object ID, finds that it already exists, and updates the existing resource instead of creating a new one.
When setting up the target system in such scenarios, you should use only xmlaccess.sh to copy resources from the source system. If you deploy portlets on the target system during the portal installation or if you deploy them using the administration portlets, they will not have the same object IDs as on the source system, so you can run into problems when you later copy other resources that reference them.

Lookup of portal resources
XML elements with locate, export, update and delete actions need to refer to existing resources in the portal. Those resources must be identified by specific attributes.
The relevant attribute to identify a resource in the portal is its object ID. Every resource must have an object ID and it must always be unique. Therefore, if you specify an objectid attribute for a resource, and you do not use symbolic object IDs as described above, the resource is looked up by that object ID.
Of course, there are cases where you do not have literal object ID values available when you write scripts, especially if you are writing scripts that are executed on installations that you are not administering yourself. Therefore you can also specify other identifying attributes to look up resources. If the lookup by object ID fails, the XML processing also attempts to find the resource using other attributes.
An alternative method for looking up portal resources is to use a unique name. Every resource that has an object ID can also have an optional unique name, and the unique name must unambiguously identify the resource. Unique names are useful if you need a symbolic way to identify certain resources. They allow easy porting of configurations between portal installations. In contrast to object IDs, it is possible to modify unique names of resources, which can be an advantage in certain situations. To set a unique name for a resource, use the Custom Unique Names portlet under Administration, Portal Settings.
If a unique name is not given or cannot be found, some resources can also be searched using other attributes. Some resources can be looked up without any attribute information, because they exist only once in their context.
The following table shows the relationship between resources and the attributes you can use for locating them.

Resource key Attributes used for locating the resources
portal, global-settings, services-settings None; these items always exist only once.
markup, virtual-resource, user, group, credential-segment, credential-slot, portlet name
event-handler classname
web-app, portlet-app uid
servlet name
refid is used as fallback for XML imports from earlier portal versions that do not contain the name attribute.
portletinstance None; there is at most one portletinstance per component.
url-mapping-context label

In any case the lookup process first tries to find the resource by its object ID, if specified, and then by its unique name, if that is specified. Only when those attempts fail, other attributes are used for locating the resource.
If an objectid attribute is specified in the XML input, but the corresponding resource cannot be found by that object ID but only by another attribute, and if that object ID is used in other parts of the XML script as a reference, those references are mapped to the actual object ID for the resource that was found. In this case the objectid attribute behaves like a symbolic object ID (see above).

Export sets of resources
You can specify more than one resource with an export action in the same request and thus generate an export response file that contains a selected group of resources, for example several portlets and pages. xmlaccess.sh provides two additional features that allow you to export selected subsets of the portal resources:
When you export a content node, you can specify the export-descendants attribute for that resource. If you set this attribute to true, the export response file also includes the entire subtree in the content hierarchy that is located below that node. In addition, all derived pages that override the layout of pages in that subtree, are also exported. In other words, this exports all content nodes that can be reached via a chain of content-parentref or derivation-parentref attributes.
Example: the following fragment exports a subtree of the content hierarchy that starts with the label as specified:
     <content-node uniquename="MyPages" action="export" 
             export-descendants="true" />   
All top level resources that can take an objectid attribute, such as...

markup
virtual-resource
user
group
client
event-handler
web-app
theme
skin
content-node
credential-segment
url-mapping-context

.support the asterisk ( * ) as a wild card symbol to be used as a value for the object ID. The asterisk can be used as a wild card symbol only with the export and delete actions. Depending on the action with which it is specified, it exports or deletes all resources of the respective type. For example: the following fragment exports the complete client configuration of the portal:
     <client objectid="*" action="export"/>    
A combination of a partial search string and the asterisk is not valid. The asterisk also has no special meaning if it is used as a value for any other attribute.
xmlaccess.sh offers no other "query" features, that allow you to export resources based on specific criteria. The only other possibility to export a selected subset of resources is to specify all the resources individually with their object IDs or other identifying attributes in XML input.

Mandatory and optional attributes
Normally, only that part of the configuration data must be specified for an XML element which is necessary for the required operation. For example, when deleting a portlet, it is sufficient to specify its reference ID to identify it; it makes no sense for this operation (although it is not forbidden), to specify a new active state, since the portlet is removed anyway.
When creating a new portal resource, some required attributes (depending on the type of resource) must be specified. Others can be omitted. They are then set to a default value.
When updating an existing portal resource, all attributes are optional, except those required to locate the element. The omitted attributes are simply left unchanged. In a few cases of page layout attributes, there is the possibility of explicitly specifying an "undefined" value. This means that the attribute is not defined at the respective level, but inherited. For example, if the skin for a component is undefined, it will be inherited from the setting of its page.
Note that there is a semantic difference between the following XML fragments:
     <content-node uniquename="MyPages" action="update" active ="true"/
and
     <content-node uniquename="MyPages" action="update" active ="true" skinref="undefined"/>
The first fragment only modifies the active attribute of the page and leaves its skin setting unchanged; the second fragment additionally resets the skin to the undefined value (whatever the previous skin setting was), so that the page will always display in the portal default skin.

Page layout modifications
When you use an XML script to update an existing page and specify a new layout for this page, that is, the content-node element for the page has child elements of type component that are created or updated, you normally use the XML script to define a complete new layout of the page instead of combining the existing layout with new definitions. Therefore XML applies special processing in this case as follows: After the layout has been updated, all components in the page that existed before but were not updated by the script are deleted. The result is that the page will only contain those layout components that are specified in the XML script and no remainders of its previous layout. Otherwise you could end up with invalid component structures.
In particular, this means that if you update a page layout in ID generating mode, all existing components of the page will be deleted and a new layout will be created instead - even if the new layout is identical to the old one. This happens because components can only be looked up by their object IDs and lookup by object ID is not possible in ID generating mode. Therefore all the components specified in the XML are created, because they cannot be found for updating, and all existing components are deleted because they were not updated.
In the rare case that you actually want to update specific components in the page but do not want to delete the existing page layout, you can turn off this special processing by specifying the attribute preserve-old-layout="true" for the content node.

Marking pages as hidden under the content root
By default, pages that you create under the content root display in the main menu. If you do not want a page that you create to appear in the main menu, you can hide the page. You do this by setting the hidden flag for the page parameter for the content-node tag in XML. Use the following XML snippet:
You can still view and work with pages that are marked as hidden in Administration portlets. You can also create a direct URL to the hidden page so that the page can be accessed from other areas of the site, such as the page menu.
<content-node action="update" ...>
    ....
    <parameter name="com.ibm.portal.Hidden" 
              type="string" 
              update="set">

    <! [CDATA [true]]></parameter>
 ...
</content-node>
Import WAR files
To create new portlet applications, additional resources (WAR files) are required. Those files are not included in the XML input. Instead, the XML input contains references to external URLs as in the following example:
     <web-app uid="MySpecialPortlet" 
              action="create">
             <url>file://localhost/C:/myportlets/Special.war</url>
     </web-app>
The referenced WAR files must be accessible to the portal when the XML request is processed. When you update a package and specify a <url> subelement, the WAR file is re-deployed, just as if you had selected the update of a portlet application in the browser. If you intend to deploy the same configuration into several new portals, you can set the URL to...
http://deploymentserver/path/filename.war

This way there is no need to copy all WAR files to each server machine. The deploymentserver machine needs to be set up properly so that the WAR files can be accessed by http.
An XML export request does not create any required archives. Instead, it only creates pseudo-references in the form of file URLs that rely on the assumption that the file resides in the deployed/archive subdirectory of the WPS installation. If these assumptions are not met, an exported portal configuration cannot be successfully re-created without editing the generated URLs manually. A back up of a portal configuration requires that the WAR files required for redeployment (which are not used in the running portal) are saved in addition to the XML export.

Import static page content from archive or compressed files
You can import the content of static pages from an external archive or compressed file. The following example imports static page content from the file index1.zip :
<content-node action="update" 
              active="true" a
              llportletsallowed="true" 
              content-parentref="homepage" c
              reate-type="explicit" 
              domain="rel" o
              rdinal="1500" t
              hemeref="ibm.theme"
              type="staticpage" u
              niquename="samplestaticpage1">
          ...
          <pagecontents markup="html" display-option="inline">
               <url>file:///$server_root$/doc/xml-samples/index1.zip</url>
          </pagecontents>
          ?
</content-node>
The referenced archive or compressed files must be accessible to the portal when the XML request is processed. For details about the administration of static pages with xmlaccess.sh refer to the topic about Using xmlaccess.sh to work with static pages.

View update of changes

Most portal data is cached on a per-user basis, therefore many modifications become visible to users only after a new logout and login. For example, a page that is created on behalf of users does not immediately become visible to those users if they are currently logged in. Other modifications only become visible after some timeout when internal caches are refreshed with current data. For some settings the portal needs to be restarted to activate the updates. Therefore, if an update you made does not become visible, restart the portal.
In general, the effect of an XML update is the same as if the update was made using administration portlets using a new browser and login session.

Transactionality

When you use XML scripts to create, update or delete resources, the changes in the portal database are grouped into transactions. All changes that are part of one transaction are either executed completely or not at all.
The XML configuration has two different levels of grouping database updates into transactions. The grouping is defined by the transaction-level attribute of the main request element, which can have the following values:

resource Every top-level resource in the XML script is processed in one separate transaction. For example, this can be a content node with its complete layout. If an error occurs, all resources up to the one where the error was encountered have been fully processed; the resource where the error was encountered is not created, or, if it already existed, it is left unchanged.
request The entire XML script is executed in one transaction. If an error occurs, all database changes caused by the script are made undone, and the original state is restored. Note that using this level of transactionality might cause large and long-running database transactions if used in large XML scripts. As a result, you might encounter database errors caused by exceeding database limits on transaction duration or transaction log size, depending on the configuration of database.
none No explicit transactions will be opened for the processing. Default.value.

Transactionality applies only to changes in the portal database. The following aspects of resources are not stored in the portal database and therefore not included in transactions:

Enterprise applications for portlets that are deployed into WAS
User and group information
Role assignments in an external access control system.

An example of what this means is as follows: When you deploy a WAR file in an XML script that uses transaction-level="request" and an error occurs later in the execution of the XML script, the transaction is canceled, so the entries for the portlet are removed from the portal database. However, the corresponding enterprise application has already been deployed into WAS and is not removed. This will not further affect the operation of the portal; you can simply deploy the portlet again later. You will just have an unused enterprise application in WAS. Remove it manually.

Error recovery
If errors occur during the processing of a script, you have generally two options to continue after fixing the cause of the error:

Re-execute the entire XML script.
Remove all resources before the point where the error occurred from the XML script and execute only the rest of the XML script.

If the error occurs during the validation of the XML script, and no resources have actually been processed so far, you can simply re-execute the entire script. You can verify this by reviewing the progress reporting comments in the XML response.
If the error occurs after some resources have actually been processed, the best option depends on several circumstances:

If you used the request transaction level, re-execute the entire script, because all changes have been undone.

If you used the resource transaction level, the preferable option is to execute only the rest of the XML script, and not to re-execute changes that have already been made; otherwise you might duplicate resources that were already created. You can only use this option if the rest of the XML script does not contain references to the resources that you are removing, that is, if you do not refer to symbolic object IDs of these resources. See Symbolic object IDs and ID generating mode for more information. You can always remove resources that have already been processed from the XML script, if script uses only hard-coded object IDs for references, because in this case all references can be resolved by looking up the object IDs in the portal database.

To make error recovery easier, use scripts that can be re-executed partially or completely without the possibility of duplicating resources. You do that by specifying an object ID or another identifying attribute on every resource in the script and by using only update actions. See Mandatory and optional attributes for more information on how to specify attributes. This way resources are simply overwritten with the same configuration if they have already been created.

Hints and tips for using the portal XML configuration interface
In an example configuration, you might have two WebSphere Portal environments which are both configured for security with an LDAP server. However, the two LDAP servers have different directory structures. For example, this can be different LDAP suffixes for the users or groups. You can use the following XML script for transferring the portal configuration from one portal to the other:
     <?xml version="1.0" encoding="UTF-8"?>
     <request
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="PortalConfig_1.0.xsd"
         type="export"
         export-users="false">
         <portal action="export"/>
     </request>
When you use this XML script to transfer the configuration data between these two environments, be aware of the following:
By setting the tag export-users to false you only prevent the export of the LDAP hierarchy. Ownership and access control rules are still exported.

During the transfer all user-related information is lost, as the target portal does not know the user information from the source portal. For example, this affects access rights or ownership of private pages. You might see a warning about missing user or group information, but it should not prevent a successful import.
If you use the above script for export, you might find that XML import fails with an exception and references one of the following two items:
Credential slots and segments.
To avoid exceptions centering around the credential slots and segments, remove the references to these elements from XML prior to running XML import.
Private pages.
The destination server cannot use information about private pages. To address exceptions centering around the private pages, use the following script for the XML export:
     <?xml version="1.0" encoding="UTF-8"?>

     <request type="update"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="PortalConfig_1.0.xsd">

         <portal action="locate">

         <content-node action="export" 
                       name="*" 
                       create-type="explicit"/>

     </portal>
     </request>
This procedure exports all pages which are not private, along with the information that is required to put the portlets on the pages. However, either deploy the portlet applications on the target portal prior to running the XML import, or modify the XML script to deploy the portlets in the same run.
Parent
xmlaccess.sh

Related
Delayed cleanup of deleted portal pages
Manage portal resources with policies
Migrate themes
Set service configuration properties
Delete orphaned data
Deregister users and groups
Changes to xmlaccess.sh for this version of portal
Sample XML configuration files
Use xmlaccess.sh to administer tags and ratings
Task refresh-iwidget-definitions
XML configuration reference
Use xmlaccess.sh to work with static pages
Automated tasks for composite applications
Work with xmlaccess.sh
Users and groups

+
Search Tips | Advanced Search

action-set	For portal internal use only.
category	For portal internal use only.
composite-app	For portal internal use only.
federation-server	For portal internal use only.
protected-resource	For portal internal use only.
resource-type	For portal internal use only.
transformation	For portal internal use only.
transformation-app	For portal internal use only.
transformationinstance	For portal internal use only.
serverref	This is a tag attribute for the content-node tag; it is for portal internal use only.
content	For portal internal use only.
supported-processing-event	For portal internal use only.
supported-publishing-event	For portal internal use only.
qname	For portal internal use only.
alias	For portal internal use only.
class-name	For portal internal use only.

localedata	Describes locale specific data associated with portal resources. The localedata element allows a number of child elements (title, description and keywords), but not all of them are supported for all portal resources. Unsupported child elements are ignored. The charset attribute is only used in markup elements. When you create XML files that contain lots of translated texts in different languages, it is sometimes more convenient to specify those texts in properties files instead of including them in the XML script. Therefore you can alternatively use a URL to specify a properties file. XML will then read the title, description, and keyword texts from that file.
parameter	Describes name-value pairs associated with portal resources. The parameter element supports a type attribute, but for all elements except portlet instances, the type must be string. Portlet instances additionally support the binary type which treats the parameter contents as Base 64 encoded binary data. User definitions support setting multiple values for the same parameter name. With all other resources, setting a parameter overwrites any previous value stored under the same parameter name. If the WSRP Producer requires a registration of the WSRP Consumer with certain registration properties, specify these properties as parameters.
preferences	This is a derivation from the name/value pair. It relates to the parameter element. It describes name/multivalue combinations, that is, combinations of a name and one or more value child elements that are associated with the portal resources wsrp-producer, portlet, and portlet-instance. The value elements support only string type attributes, no binary type attributes. Set a preferences value overwrites all values that were previously stored under the same preferences name. portlet and portlet-instance can only have the preferences element if they comply with the standard portlet API. For all other portlets, use the parameter element. If the WSRP Producer requires a registration of the WSRP Consumer with certain registration properties, specify these properties with the parameter tag. Optionally, you can use the preferences element to define which user attributes you want to have transferred in the WSRP communication with the Producer. These user attributes are the user attributes defined in LDAP.
access-control	Describes the access permissions associated with portal resources. By specifying access-control subsections for resources in the XML, you can, for example, define which users or groups are allowed to manage a resource. The access control definition for a resource includes all of the following information: The owner of the resource The roles defined on that resource The mapping of users or groups to a role Whether inheritance of a role or from the parent resource or to child resources is blocked. Alternatively, a resource can be a private resource of a specific owner, or it can be managed externally. When you specify users or groups in the access-control section of a resource, you can either use the full DN as in... uid=wpsadmin,cn=users .the short ID as it is used for portal login, for example wpsadmin. An XML response file from a portal export request always contains full DNs. When you change the access control state of a resource from public to private or vice versa, this also affects all the resources that inherit access control from this resource. You can never have a public resource that inherits access control from a private resource.
objectid	Almost all resources in the portal have an object ID, which identifies the resource. The object ID allows addressing the resource unambiguously. It is also used to express references from one resource to another. For example, when a theme is assigned to a page, the configuration of the page includes the object ID of the theme. See the Object IDs in XML scripts section on object ID handling in XML scripts for more information.
uniquename	A resource that has an object ID can optionally also have a unique name. The unique name can then also be used to identify the resource unambiguously, because a unique name can be used only once in a portal installation. If you execute an XML update that assigns a unique name which is already used on the system, the execution will fail. You can delete the unique name for a resource by setting it to the value undefined. When you create unique names in XML scripts that you run on many different portal installations, for example to install add-on portlets and pages, you should use a specific prefix for any unique names that you assign, to minimize the chances that they clash with existing unique names on the system. For example, the prefix wps. is used for all unique names that are created as part of the portal installation. When you create a nested element, for example a component, with a uniquename attribute, the whole hierarchy upward from that element must also have uniquename attributes. Example XML export request snippet: <content-node ... <component uniquename="component_1"... <component uniquename"component_2"... <component uniquename"component_3"... ..... </component> </component> </component> </content-node> Failing to do so might result in the following error message: XMLC0142E: Unique name unique_name is already used in the portal.
ordinal	The client and component resources take an ordinal attribute which represents the sorting order. (In the case of client resources, if more than one client entry matches a connecting device, the entry with the higher ordinal takes precedence.) When ordinals for resources are set in an XML script, you have the following options for specifying them: As a plain integer value. In this case, the value is written to the database. The resource is sorted into the position that this ordinal value has relative to the ordinals of existing siblings. For example, if you create a new page with ordinal="350" under an existing label, and there are already other pages under that label with the ordinals 100, 300 and 500, the new created page will appear in the third position. If you specify an ordinal which has already been assigned to an existing resource, the order of the two resources cannot be predicted. As a position indicator. Specify with a hash mark ( # ), followed by an integer value. In this case the resource is inserted in the sequence of resources at the position indicated by the specified value. For example, when you create a new page with ordinal="#2", it appears in the second position in its content parent. The special values first and last. In this case, a value is chosen so that the resource is sorted at the first or last position in its content parent. An XML export response file always contains the literal ordinal values as they are stored in the portal database. Note that specifying a position indicator or special value will not necessarily produce the required effect if you are working with derived pages, because in these cases the order of elements depends on the individual user viewing the portal.
domain	Use this attribute to specify in which database domain a specific resource should be stored. You can also use the domain attribute to export release data from the portal database by specifying domain="rel" to later feed that data it into the staging process. Use one of the following values with the domain attribute:
rel	Export only the release data.
cust	Export the release data with the customization data. This includes all referenced release data as locate statements. Export composite applications is not supported. To export composite applications use the back up and restore feature.
export-release	This attribute is for use with the request tag. Do not use this attribute any more. Instead, use the domain attribute (above) by specifying domain="rel". The following two attributes have been added for the portletinstance tag. Use them for personalized content, where only portlet parameters are changed, but not the page structure.
owner	Define the owner of the portletinstance.
parentref	Define the parent of the portletinstance.

Action	Resulting processing
locate	Identify the portal resource corresponding to this XML element (usually required as a context for other actions).
create	Create a new portal resource with the given attributes. A new resource is always created, even if another resource with the given name already exists.
update	Update the configuration of the corresponding portal resource with the given configuration data (attributes and dependent configuration data elements); if no corresponding portal resource can be found, it is created.
delete	Delete the portal resource corresponding to this XML element.
export	Include an XML representation of the portal resource corresponding to this element in the output of the XML command.

Action	Allowed actions in subelements
locate	locate, create, update, delete, export
create	locate, create, update
update	locate, create
delete	no subelements allowed
export	no subelements allowed

update	Resulting processing
set	The corresponding configuration data (for example, parameter) is set, or, if it does not yet exist, it is created.
remove	The corresponding configuration data (for example, parameter) is removed

Resource key	Attributes used for locating the resources
portal, global-settings, services-settings	None; these items always exist only once.
markup, virtual-resource, user, group, credential-segment, credential-slot, portlet	name
event-handler	classname
web-app, portlet-app	uid
servlet	name refid is used as fallback for XML imports from earlier portal versions that do not contain the name attribute.
portletinstance	None; there is at most one portletinstance per component.
url-mapping-context	label

resource	Every top-level resource in the XML script is processed in one separate transaction. For example, this can be a content node with its complete layout. If an error occurs, all resources up to the one where the error was encountered have been fully processed; the resource where the error was encountered is not created, or, if it already existed, it is left unchanged.
request	The entire XML script is executed in one transaction. If an error occurs, all database changes caused by the script are made undone, and the original state is restored. Note that using this level of transactionality might cause large and long-running database transactions if used in large XML scripts. As a result, you might encounter database errors caused by exceeding database limits on transaction duration or transaction log size, depending on the configuration of database.
none	No explicit transactions will be opened for the processing. Default.value.