+

Search Tips   |   Advanced Search

xmlaccess.sh


Overview

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

xmlaccess.sh connects to the server using HTTP or HTTPS, allowing remote configuration of portal.

To recreate source portal A on target portal B...

xmlaccess can be used for quick back ups of data, as long as the volume of data is not too large.

Portal provides sample files... 

/opt/IBM/PortalServer/doc/xml-samples ->ls *.xml
ActivatePortlet.xml              DeletePage.xml                     ExportTagsAndRatings.xml
CleanSystemSlots.xml             DeletePortlet.xml                  ExportTasks.xml
CleanupUsers.xml                 DeleteTagsAndRatings.xml           ExportThemesAndSkins.xml
ClonePortlet.xml                 DeleteUser.xml                     ExportUniqueRelease.xml
CopyPage.xml                     DeployPortlet.xml                  ExportUserResource.xml
CreateAnalyticsTags.xml          DeployTheme.xml                    ExportWSRPCustomizedPortletInstances.xml
CreateApplicationFolder.xml      DeployThemeFromWebModule.xml       ExportWSRPProducer.xml
CreateCsaPage.xml                Export.xml                         ExportWSRPProducersAndPortlets.xml
CreateFilter.xml                 ExportAllPolicyNodes.xml           FederationDeletion.xml
CreateLanguage.xml               ExportAllPortlets.xml              FederationImport.xml
CreateLegacyPage.xml             ExportAllUsers.xml                 IntegrateRemotePortlet.xml
CreatePage.xml                   ExportAnalyticsTags.xml            ModifyPortlet.xml
CreatePageFromTemplate.xml       ExportIncludingOrphanedData.xml    MovePage.xml
CreatePageFromZip.xml            ExportManagedPagesRelease.xml      RegisterPreDeployedEAR.xml
CreateTagsAndRatings.xml         ExportPage.xml                     Task.xml
CreateTemplateFolder.xml         ExportPageResult.xml               Transaction.xml
CreateUrl.xml                    ExportPortletAndPage.xml           UpdateAccesscontrol.xml
CreateUser.xml                   ExportPortletAndStaticPage.xml     UpdateFilter.xml
CreateWSRPProducer.xml           ExportRelease.xml                  UpdatePortlet.xml
DeleteAnalyticsTags.xml          ExportStaticPage.xml               UpdateVault.xml
DeleteFilter.xml                 ExportSubTree.xml


Usage

 
xmlaccess -user user_ID  \
          -password password  \
          -url myhost:10039/wps/config  \
          -in input_file.xml  \
          -out result_file.xml

To be prompted for user and password. 

 
xmlaccess -askForCredential  \
          -url myhost:10039/wps/config  \
          -in input_file.xml  \
          -out result_file.xml


Virtual portals

We can access a virtual portal by its host name or its URL mapping context.


xmlaccess.sh elements

Element Description
xmlaccess.sh Shell script located in WP_PROFILE/PortalServer/bin
-in Name of file containing the XML request
-user and -password Short user name of user with manager role on virtual resource XML_ACCESS, and administrator role on virtual resource PORTAL. Full distinguished names are not supported.
-askForCredential Leave out the parameters user and password. xmlaccess.sh will prompt for user ID and password.
-useEncryptedCredentials Provide the user credentials in a properties file.
-noUpdateProperties Do not write encrypted credentials back to the properties file. Used in conjunction with -useEncryptedCredentials.
-url Base URI and servlet extension. For example /wps/config
-out Name of the result file containing the XML output. For XML exports, the exported configuration which can later as an import file.


XML input and output

An XML file that you process must always be in UTF-8 encoding and must specify the following root element and schema: 

 
<?xml version="1.0" encoding="UTF-8"?>

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

For an XML export, specify export for the request type. For an XML import, specify a request type of update, together with the create or update action for the resources to be imported.

When the XML request has been processed on the server, the resulting XML output is sent back to the client and written to the standard output in a console encoding that depends on the operating system and active locale. It may therefore be invalid XML. To ensure valid XML, write the output to an XML file using the -out command line option, which writes the output in UTF-8 encoding.


Exports vs. Imports

The command line syntax and XML processing is the same for both exports and imports. You specify an XML input file to xmlaccess.sh, and xmlaccess.sh returns a resulting XML file.

The difference between export and import is determined by whether set the request type to export or update in the XML file specified in the command line request. When importing, the resources action attribute can have the following values: locate, create or update.

The normal procedure for exporting a configuration or part of it and then importing it to another consists of the following steps:

  1. Run the XML command line interface with a file that has a request type of export in it. We can use one of the XML sample files with request type export supplied with WebSphere Portal. The XML command line interface returns a result file containing the resources specified in the XML file used for the export. This can be, for example a resource and all dependent resources. The file returned by the XML command line interface has specified update for the request type and locate or update for the individual resources actions. This file is ready to be used for an XML import.

  2. This step is optional: Modify the XML result file from the export as required, for example to create additional resources using create or update.

  3. Run the XML command line interface, specifying the XML file that resulted from the XML export and that we might have modified. We can also use one of the XML sample files with request type update in it. The XML command line interface returns a result file that indicates whether the specified resources were imported successfull.


Transfer a complete configuration

To transfer a complete portal configuration, use the WebSphere Portal Release Builder.

For information about how to move a complete configuration from a test to a production server refer to Staging - transferring a release configuration.


Staging - transferring a release configuration

To move a complete configuration from a test to a production server using the portal ReleaseBuilder tool, use the sample file ExportRelease.xml. The attribute domain="rel" indicates that only shared (as opposed to private) resources are exported. This sample file exports the complete portal configuration without private resources as required by the portal ReleaseBuilder tool.


Export and transfer parts of a portal configuration

To export partial configurations, specify the XML hierarchy down to the specific portal resource to export. The element itself has an export action. Parents are specified with a locate action.

The sample XML request file ExportPage.xml exports a page with the unique name...

Note that this page does not exist in a newly installed portal. We can create it by executing the DeployPortlet.xml sample file, which is covered in the next section.

Normally, we specify the resources to export by their object ID or by their unique name. We can use the Custom Unique Names administration portlet to look up object IDs and unique names of portal resources. Some resources also support lookup by other attributes;

Executing the ExportPage.xml example request file mentioned earlier results in an XML file similar to ExportPageResult.xml. We can use this file to update the page to the exported state, if it still exists in the portal. We could also use this file to re-create the page, in case you delete it later.

When you look at the file, you notice that it includes not only the page itself but also other configuration elements that are referred to by the page, for example the portlet placed on the page. These other elements have a locate action. The export does not include their full configuration data, but just enough information to look them up in the portal, assuming they already exist. Note how the configuration of the page makes references to the objectid attributes of other resources, for example in the portletref attribute of the portletinstance elements.

All those references are described by object IDs. If the object IDs are correct, the referenced resources could be looked up in the portal even if they were not included in the export. Locating resources before they are referenced is only necessary if you do not know their actual object IDs, so the resources need to be found by some other identifying attribute (see the XML reference documentation). That way, for example a portlet can be identified by its name and by the uid attributes of its parents, and the referencing will still work, even if the object ID is not available for looking up the portlet.

Export resource configurations normally creates update actions for all exported elements. This means that if the portal resource already exists on the importing system, the settings are modified, and if it does not yet exist, it is created. This in turn means that if you re-import the page into the portal that you exported it from, nothing changes.

We can import the XML file into another portal to create a copy of the page. This requires that the referenced resources (such as the portlet and the content parents) also exist on the target portal and can be found by an identifying attribute. In that case, the page and all contained resources take their object IDs with them, so that they have the same object IDs on the source and target system - the resources retain their identity.

We can avoid that using the ID generating mode (see the XML reference documentation for detail). When we use the ID generating mode, the object IDs in the input are not taken literally, but during the import process the resources obtain new object IDs when they are created on the target system. You apply ID generating mode by adding the following attribute to the main request tag:

We can create a duplicate of the page in the portal from where you exported it using the ID generating mode and changing the unique name of the page in the XML script. This way, the page and its changed name cannot be found for updating by either its object ID or its unique name, therefore a new page with the same settings is created. If you do this, you should change the page title as well, so that we can distinguish between the two pages. The CopyPage.xml sample shows how this script would look.

When exporting resources to XML scripts, it is possible and often useful to export several resources using one request. The ExportPortletAndPage.xml example extends the ExportPage.xml example by including also the portlet that is contained on the page. The resulting XML file contains the complete configuration data of the portlet and the page.

The ExportSubTree.xml example shows how you export subtrees of the portal content hierarchy. It exports parts of the predefined administration page hierarchy that was created during the portal installation.

Use wildcard characters:

When you export portal resources, we can specify the asterisk ( * ) as a wildcard character for tag attributes. Be aware of the following limitations:

  1. The asterisk wildcard character is supported for attributes of top level tags onlythat is subtags of the portal tag.

  2. Specify the asterisk wild character for the object ID attribute of tags as follows: objectid='*', except for policy-node tags, where we can specify it for the path attribute.

  3. Specify only the asterisk alone: "*". The asterisk does not work in combination with partial strings that precede or follow it.

    For example, we cannot specify "abc*" or "*xyz".

  4. If we specify the asterisk as a wildcard character, all other attributes on that tag are ignored, except for the following tags, where the listed attributes are interpreted as filters:

    • The tag content-node, attribute create-type

    • The tag tag, attribute locale .

The ExportAllPortlets.xml example shows the use of the asterisk character ( * ) as a wildcard to export all resources of a given type. This example exports all the web modules that have been installed in the portal and their contained portlets.


Create and modify resources

In addition to copying and restoring configurations of existing resources, we can also use xmlaccess.sh to install new resources in the portal or as an alternative to the user interface for performing some administration tasks. In these cases, we cannot simply export and re-import XML scripts, but you have to edit them. In most cases, it is still useful to start with an XML export and only partially modify it, rather than writing complete new XML scripts. The following scripts show examples for modifying different resources in the portal configuration using XML scripts.

Note that all the examples use the ID generating mode and do not specify literal object IDs. Therefore they can be executed on any portal installation and do not depend on hard coded object ID values. As noted earlier, using literal object IDs only makes sense if you really want to create two instances of the same resource, and if you have a controlled environment where we can guarantee that all object IDthat the resources depend on have exactly the required values. As object IDs are difficult to use for identifying the resources, the examples assign unique names to most top-level resources. This way they can be referenced later, and the resources are not duplicated if you execute the scripts twice.

DeployPortlet.xml shows how you deploy a portlet and create a simple test page to display the portlet. Note that some of the attributes in the XML must match the corresponding settings that were defined in the portlet.xml deployment descriptors in the portlet WAR file. This is necessary so that the XML processing can properly identify the contents of the WAR file. When to deploy a different portlet, you must not only specify a different WAR file but also adapt those attributes. Also note that the configuration specified for the portlet is less than what you see in an XML export result for the portlet.

For example, the localized titles are not included in the XML script. This is because those settings are specified in the portlet.xml deployment descriptors; there is no need to override them with xmlaccess.sh.

As Windows limits the maximum path length to 260 characters, the name of the WAR file must be 25 characters or less. Deploying a WAR file with a name that is more than 25 characters will result in an error.

The CreatePage.xml sample shows the following additional possibilities:

  1. It assumes that the portlet is already installed. Therefore it only uses a locate action for the web module, not an update action.

  2. It sets a specific skin for displaying the portlet on the page.

  3. It shows how we can specify localized titles in properties files rather than include them in the XML script: the titles and descriptions for the page are now loaded from two properties files for two different languages.

Both examples use a simple page layout with just one row and one column. To generate more complex page layouts, we can use the administration portlets to create them. We can export the result to generate a template for the XML scripts.

UpdateAccesscontrol.xml shows the syntax for specifying different access control settings. This sample updates existing resources, but we can of course use the same syntax to define access control settings for new resources while creating them in an XML script. This sample also shows how we can specify access control user roles on virtual resources. This allows us to give a user access to all resources of a specific type that exist in the portal.

CreateURL.xml defines a URL mapping for the sample page that was created with the DeployPortlet.xml example mentioned earlier. After creating the URL mapping we can access the page directly by entering that URL in the browser.

DeployTheme.xml installs new themes and skins into the portal. Be aware that the XML scripts create these resources only in the portal database, so that they can be used in the portal. In addition, you have to write the JSPs that perform the actual visualization and copy them to the resource directory specified in the XML before we can use the theme in the portal.

ModifyPortlet.xml changes settings of a portlet instance that is shown on a page. Such settings are normally set in the edit mode of the portlet. It depends on the code of the portlet which settings are stored and how they are used.

CreateUser.xml imports a new user into the portal. It also creates a group containing only that one user.

CreateLanguage adds a new language to the portal. To prepare for running this XML script, insert resource bundles and, where applicable, JSPs for the new language.

UpdateVault.xml demonstrates how to create new resources in the portal credential vault with an XML script.

ClonePortlet.xml adds new portlets with different settings to existing applications.

Transaction.xml demonstrates the effect of using different transaction levels for the execution of an XML import.

MovePage.xml moves a page to another node. The actual move of the page is done by the last two lines in the sample file. They are highlighted in the representation of the sample file here.


Activating and deactivating portlets, portlet applications, and web applications

We can change the states of portlets, portlet applications, and web applications between active and inactive using the portal XML configuration interface. The ActivatePortlet.xml example shows you how to do this.


Scheduling the delayed cleanup of portal pages

The Task.xml example shows you how to schedule the cleanup of pages that have been marked for deletion.

  1. 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, we might receive an error message indicating the operation was canceled because it would have caused a duplicate key value.

  2. When you run the cleanup task, xmlaccess.sh only schedules the task to be run in WAS and returns. This does not necessarily mean that WAS runs the task immediately. To determine when a task started and ended, check the portal log SystemOut.log for the EJPDE0005I and JPDE0006I messages. These messages confirm that the cleanup task has successfully completed. After you have confirmed this, we can run the XML script for re-creating a page with the same object ID as it had before the deletion.


Registering predeployed portlets

We can manually predeploy portlet application WAR files using the WAS admin console. We can later register and configure the predeployed portlet applications into WebSphere Portal, together with other J2EE resources and artifacts, using xmlaccess.sh. Use the sample file RegisterPreDeployedEAR.xml to install a predeployed portlet. .


Deregister users and groups

If portal users or groups have been removed from the user registry, but not from the portal database, or if users have had their user ID deactivated, for example after too many wrong password attempts, we can identify and list these users and groups using the cleanup-users attribute. Specify the cleanup-users attribute with the request tag of type export, and set its value to true . We also need to set the export-users attribute to true.

The CleanupUsers.xml sample file shows an example of how we can export such users and groups. The resulting output file lists the affected users and groups with their action set to delete. You need to check the list and remove all users and groups to keep in the portal database.

For example, we might want to keep the muted users and re-enable their passwords. After you have done this, import the file into the portal. All users and groups that remain in the list are removed from the portal database.

After deleting these entries via the modified XML script, all customization is lost for the deleted users and groups.


Preparing the deletion of orphaned data

To prepare for deleting orphaned data, use the ExportIncludingOrphanedData.xml example to perform an export that includes all orphaned data.


XML configuration reference

This document describes...

The XML configuration interface only manages resources of the portal core and not those of additional components, such as personalization.


XML input structure

The top level structure of an XML request or response is always as follows: 

<?xml version="1.0" encoding="UTF-8"?>
   <request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:noNamespaceSchemaLocation="PortalConfig_8.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 main request element specifies the XML schema used by xmlaccess.sh. All XML requests must conform to this schema. We can find the schema declaration in the JAR file wp.xml.jar under...

The JAR file wp.xml.jar is located in:

All other XML sample files are located in the following directory:

Before sending requests to the portal, we can verify them against this schema using a suitable editor or parser to ensure syntactic correctness. The schema contains annotations that provide information on the meaning and possible values of all configuration entries.

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 simplest request that we can send to a server is the following: 

   
<?xml version="1.0" encoding="UTF-8"?>

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

This request exports the entire configuration of the portal. We 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.


XML tags for portal resources

Portal resource tags:

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.


Administer tags and ratings

The following tags are available for portal resources for tagging and rating:

See: Using xmlaccess.sh to administer tags and ratings.


Special configuration data entries

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.

We 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:

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 anothen 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 updata 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 Ithat 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 containing 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="Z3_G0Q03FH200A5202QRHAG4320G0" 
             ... >
          ...
    <portletinstance action="update" . . . portletref="Z3_G0Q03FH200A5202QRHAG4320G0" . . . >

All resources get an object ID assigned in the portal when they are created. That object ID can not be altered later. When created new resources in the portal administrative user interface, they automatically get a new object ID generated by the portal. When creating a new resource with XML, it also always gets a new object ID, if you do not specify one in the XML. Note that we 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:

We can use object IDs to uniquely specify resources 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="Z6_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="Z6_G0Q03FH200A5202QRHAG4320O0" 
                  type="page" 
                  ... >

The next snippet creates or updates a theme with a specific object ID and then assign that theme to a label: 

   
    <theme action="update" 
           objectid="ZJ_G0Q03FH200A5202QRHAG4320S1" 
           ...>
        ...

    <content-node action="update" 
                  objectid="Z6_G0Q03FH200A5202QRHAG4320O0" 
                  type="label" 
                  themeref="ZJ_G0Q03FH200A5202QRHAG4320S1" 
                  ... >

If the theme already exists with the specified object ID, we 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="Z6_G0Q03FH200A5202QRHAG4320O0" 
              type="label" 
              themeref="ZJ_G0Q03FH200A5202QRHAG4320S1" 
              ... >

In this case, the theme is looked up in the portal data store using its object ID ZJ_G0Q03FH200A5202QRHAG4320S1. If no theme wito that object ID is defined in the portal, you get an error during the XML validation.

An object ID is globally unique. Two object IDthat were automatically generated by different portal installations can never be the same. Therefore we can exchange resources between different portal installations using XML export and update requests without having to worry about possible object ID conflicts. The only was that we 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 to create a new resource instead, regardless of existing OIDs and without any chance of causing conflicts, you must 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, we might need to use objectid attributes to express references between resources in the 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, we might want to create a new theme and page, and reference the theme in the page. Nevertheless 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:

Note that even in symbolic object IDs, anything after the first space is not significant for processing.

For example, we 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, we cannot use them in a reference without first "defining" them in the same XML script. Before we 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 instead. For details see the information later in this section. 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 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. We 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 to create an XML script that installs a group of new resources and is executed on 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 Work 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 use "real" object IDs in your scripts, when you want the objects in the XML to retain their identity.

For example, when we 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 we 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, findthat it already exists, and updates the existing resource instead of creating a new one.

When setting up the target system in such scenarios, 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 we 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. If we specify an objectid attribute for a resource, and you do not use symbolic object IDs as described earlier, 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 we write the scripts, especially if we are writing scripts that are executed on installatione that we are not administering yourself. Therefore we 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 with 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...

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 we 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
web-app, portlet-app uid
servlet name

The 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, 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 is 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 as described earlier.


Export sets of resources

We can specify more than one resource with an export action in the same request and thus generate an export response file containing a selected group of resources, for example several portlets and pages. xmlaccess.sh provides two additional features that allow us to export selected subsets of the portal resources:

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.

The XML configuration interface offers no other "query" featureso that allow us 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 the XML input.


Mandatary 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 you update an existing portal resource, all attributes are optional, except those required to locate the element. The omitted attributes remain 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 we use an XML script to update an existing page and specify a new layout for this pages that is, the content-node element for the page has child elements of type componencreated or updated, you normally use the XML script to define a complete new layout of the page instead of combining the existing layout with the 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 specified in the XML script and no remainders of its previous layout. Otherwise we could easily 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 caso that you actually want to update specific components in the page but do not want to delete the existing page layout, we 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 created under the content root display in the main menu. If you do not want a page that created to appear in the main menu, we 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:

We can still view and work with pages that are marked as hidden in Administration portlets. We 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, we 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

We 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" 
              allportletsallowed="true" 
              content-parentref="homepage" 
              create-type="explicit" 
              domain="rel" 
              ordinal="1500" 
              themeref="ibm.theme"
              type="staticpage" 
              uniquename="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 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. 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 we 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:

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:

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; we 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:

  1. Re-execute the entire XML script.
  2. 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, we can simply re-execute the entire script. We 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:

To make error recovery easier, use scripts that can be re-executed partially or completely without the possibility of duplicating resources. You dthat by specifying an object ID or another identifying attribute on every resource in the script and using only update actions. See Mandatary 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.


Tips for using the portal XML configuration interface

In an example configuration, we 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. We 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_8.0.0.xsd"
         type="export"
         export-users="false">
         <portal action="export"/>
     </request>

When we use this XML script to transfer the configuration data between these two environments, be aware of the following:

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

  2. 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.

  3. If we use this script for the export, we might find that your 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 the XML prior to running the 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_8.0.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 required to put the portlets on the pages. However, you must 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.

See also


Use xmlaccess.sh to work with Producer definitions


We can use xmlaccess.sh to work with WSRP Producer definitions in different ways.

If we use xmlaccess.sh to create a Producer definition, we can work online or offline. Depending on these scenarios, you need to consider some differences.

We can also use xmlaccess.sh to export a WSRP Producer definition, and to create a Producer definition and consume a WSRP service from that Producer using a single XML script.

See also...

  1. Create a Producer definition offline
  2. Use xmlaccess.sh to create a Producer definition
  3. Export a Producer definition using xmlaccess.sh
  4. Create a Producer definition and consuming a WSRP service by a single XML script


Use xmlaccess.sh to consume WSRP services from a Producer portal

We can use xmlaccess.sh to consume WSRP services from a Producer portal.

To consume a WSRP service using xmlaccess.sh, specify the handle of the remote portlet and the Producer portal that provides the remote portlet. Specify this information using the attributes remotehandle and wsrp-producerref with the servlet subtag. Both values are required to use the remote portlet. The remotehandle attribute is defined by the owner of the Producer portal. The owner of the Producer portal provides the handle to you by appropriate means, such as fax, phone, or email. If we cannot access this information, use external tools such as the Apache WSRP Open Source implementation to find out which WSRP services the Producer has to offer.

Producers with an IBM WebSphere Portal Producer can obtain this information by exporting all provided portlets on their Producer portal by using xmlaccess.sh.

subtag Attribute for the subtag Description
servlet remotehandle As provided by the Producer
servlet wsrpproducerref ID of the Producer

After successful integration, the remote portlets are available in the portal administration. They are handled in the same manner as local portlets.

Notes:

  1. We can consume a WSRP service only if you work online and can access the Producer's WSDL document.

  2. The WSRP implementation of the portal does not yet make use of public WSRP services registries, such as UDDI, to discover and consume WSRP services. Instead, it uses the discovery mechanism of WSRP services defined in the WSRP standard to obtain a list and descriptions of the WSRP services that a certain Producer provides.

  3. An integrated portlet is always treated as a standard API compliant portlet.

To delete integrated remote portlets, use the Manage Web Modules portlet.


Sample files are provided for the reference to help illustrate how to use XML configuration for different portal configuration purposes. Before we use them, read the other topics about xmlaccess.sh carefully. Many of the samples need to be modified with valid page or user name before they can be used.


Sample file location

The sample XML configuration files provided with the portal are located in the following directory: PORTAL_HOME/doc/xml-samples.


Sample file list

Some of the XML samples are listed in the following. This list is not complete. All samples are located under the directory given in the previous section.


Parent: xmlaccess.sh
Related:
About xmlaccess.sh
Related:
Deploy J2EE resources with portlet application WAR files
Export a Producer definition using xmlaccess.sh
Create a Producer definition and consuming a WSRP service by a single XML script
Related reference:
Changes to xmlaccess.sh for this version of portal
XML configuration reference
XML samples for creating Producer definitions
XML samples for creating or removing language definitions
Related:
Work with xmlaccess.sh


xmlaccess.sh and managed pages

We can use xmlaccess.sh to manipulate managed pages just as we can for other portal resources.


Project scope

When using xmlaccess.sh with managed pages, processing occurs either completely within a project or completely outside a project.

When you import a published page and specify a project scope, the page is created as a draft page in the project.

We cannot export a draft page and then import that page as a draft in another project.

To run the xmlaccess command from within a project, specify the project either with the project name or with the object ID of the project. The command uses the following format, depending on how you identify the project:

For example:

You might need to precede the percent sign ($) with a backslash (\) to prevent $project from being interpreted as an environment variable.

For example:


Use transaction processing with xmlaccess.sh

Because managed pages are stored in the Portal Site library in Web Content Manager, each page has corresponding objects in the JCR database. Be aware of this relation when created, update, or delete managed pages with xmlaccess.sh. If xmlaccess processing is interrupted, it can result in a mismatch between the page state and database state.

To ensure that page and database information for a managed page remain synchronized, use the transaction-level attribute of the request element in the XML file.

Example: 

<request type="update"      
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      
         xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd"
         transaction-level="resource">


Use xmlaccess.sh to work with static pages We can work with static portal pages using the portal xmlaccess.sh. Exporting a static page using xmlaccess.sh works like exporting any other portal page. We can import a static content page into the portal using one of the following three methods:

See also...


Security considerations

To use xmlaccess.sh, assign role@resources of...

This implies that you must be a super administrator of the portal, who can perform any action. Consequently, there are no further access control checks that could restrict the actions when we use xmlaccess.sh; you may view all resources in the portal and you may update and delete all resources.

With HTTP connections, the user and password are sent to the server unencrypted. To protect connections from being compromised, run xmlaccess.sh from inside a protected intranet. For other networks, use a secure HTTPS connection.


Changes to xmlaccess.sh for this version of portal


Changed XML schema

Verify scripts specify the correct version of the XML schema. For example, for Websphere portal v8.0 specify: 

   
<?xml version="1.0" 
      encoding="UTF-8"?>

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

Syntax definitions:

WebSphere Portal Version XML schema
v7.0.0 7.0.0
v7.0.0.2 7.0.0_2
v8.0 8.0.0


Backward compatibility

Later XML schemas are backward compatible with earlier supported versions of WebSphere Portal. For example, we can run an XML script that is based on the PortalConfig_7.0.0.xsd under Websphere portal v8.0. A warning message is written to the output script, indicating that a previous version of the XML schema was used.


Schema file naming convention

If the XML schema is enhanced by updates, a new version of the xsd file with a new file name is created according to the following naming convention:


New XML resources in WebSphere Portal v8.0

tags Portal resource
device-class device class
global-target-settings Cross-page wire settings set as global targets
target Global target


New XML attributes in WebSphere Portal v8.0


Removed XML resources in WebSphere Portal v8.0

The following XML resource is no longer supported in Websphere portal v8.0:


Set the project scope in WebSphere Portal v8.0

The managed pages feature enables you to edit portal resources, such as pages, in the scope of a project. By working in a project, we can create, update, and approve pages in a draft state, without affecting the live server. We can specify a project scope for actions performed with xmlaccess.sh command by including the object ID of the project in the URL.


Overall structure of the XML input and output

Types of requests that can be sent to xmlaccess.sh:

Requests to and responses from xmlaccess.sh use the same XML format. An export request generates an XML response containing all the configuration data required to re-create the exported configuration part. We 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.

The XML schema is in wp.xml.jar under:

Unpacking wp.xml.jar provides schema...

An XML request contains the following:


Representation of a portal configuration in XML

The XML hierarchy 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.:

XML element Description
portal Main element of every XML request
global-settings Global portal settings
services-settings Global portal settings for portal services
language Languages defined in portal
task Tasks used to schedule programs
action Actions used to create action sets
action-set Action sets used to create roles. They are also known as Role Types.
virtual-resource Virtual resources that have associated access control settings
resource-type Resource types used to create custom resources.
protected-resource A resource instance that is protected by Portal Access Control (PAC).
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
device-class Device class information
skin Visual appearance settings that can be applied to user interface elements
theme General visual settings that can be applied to the user interface
wsrp-producer Producer of Web services as defined in the consumer portal
wsdl-url The URL to the Producer's WSDL document
porttype The URL to the service description, markup, registration, or portlet management of the Producer
web-app Web modules containing portlets
url The WAR file containing the Web application
context-root The context root assigned to the Web application of the portlet application in the predeployed EAR file (reference: application.xml)
display-name The name assigned to the application in the predeployed EAR file (reference: application.xml)
servlet Servlets defined in the Web module
portlet-app Portlet applications defined in the Web module
portlet Portlets defined in the portlet application
federation-server The federation server definition. Used to retrieve content nodes.
content-node Elements of the portal content tree (pages or labels)
supported-markup The markups that are supported by this content node
allowed-portlet The portlets allowed on this page
component Layout components of pages
component Subcomponents in the structure of the page
portletinstance Occurrences of a portlet on a page with customized settings
cross-page-wire Property broker wiring between two portlet instances. The wire tag has been deprecated with WebSphere Portal v7, 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.
credential-segment Segments for storing credentials in the credential vault
credential-slot Slots in a credential segmenu that hold a credential
url-mapping-context User defined URLs that map to pages in the portal
user-resource Allows exporting and deletion of a specific user resources.
policy-node Policies defined in the portal
application-role A named set of authorization roles that can be assigned to users or groups.
wsrp-customized-portletinstance A customized occurrence of a portlet provided by WSRP on a Producer portal
custom-resource A custom resource that can be tagged or rated by users
category-instance A category assigned to a custom resource
tag A tag applied to a resource by a user
rating A rating applied to a resource by a user
filter-instance A filter for preprocessing data before the data is finally stored.

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.


XML configuration through administrative portlets

XML configuration through administrative portlets allows us to export and import configurations. We can export a page or an entire page hierarchy by clicking the Export icon in the Manage pages administration portlet. We can also import an XML configuration file using the Import XML portlet.

To export a page or an entire page hierarchy using the Manage pages portlet:

  1. On the Manage Pages portlet, click the Export button for a specific page.

  2. You are then asked to export the entire page hierarchy or only the selected page. Select one of the following options:

    • Click Yes to export the entire page hierarchy.
    • Click No to only export the selected page.
    • Click Cancel to stop the page export.

  3. If we selected Yes or No in the previous step. we are prompted to save the configuration file. Provide a file name and select the location where you want it saved.

  4. When the export is complete you see a success message.

  5. Check the content of the saved XML configuration file to make sure that a <failure> tag does not exist. On the Download complete screen, click Open to view the newly saved XML file. If you do not want to view the XML file, close the extra window that is open for viewing the file.


Import an XML configuration file using the Import XML portlet

  1. On the Import XML portlet, locate the xml configuration file to import.
  2. Click Import to import the configuration.
  3. When the import is complete you see a success message.


Use xmlaccess.sh remotely from a machine that does not have portal installed

To use xmlaccess.sh remotely from a machine that does not have portal installed, copy the four required files to the remote machine and configure the portal from there. All you need is a Java run time. These are the required files:

The following files need to be set in the script's PATH settings

Adapt the path settings in the shell scripts accordingly. When you update the portal by installing fix packs, these files might be updated. Always use the most recent versions of these files.


Secure connections


Encrypt credentials

We can place xmlaccess.sh credentials in a properties file, and then use flag -useEncryptedCredentials, which reads the encrypted or unencrypted credentials from the properties file, and then saves the file back using the encrypted password. To not write the properties file back with the encrypted credentials, use flag -noUpdateProperties.

We can use PropFilePasswordEncoder.sh to encrypt the password in the properties file. This option reads the following properties out of the file:

For example 

xmlaccess -in Export.xml  \
          -useEncryptedCredentials myProperties.properties \
          -url portal.example.com:10039/wps/config

To use xmlaccess.sh with SSL over a secure HTTPS connection...

...where...

Element Description
-truststore Name of the truststore file containing the server certificates required for accepting SSL connections with trustedservers. If no truststore is provided, the XML client will use the default Java cacerts truststore.
-trustpwd Password required for accessing the truststore. If the default Java cacerts truststore is used, no trust password needs to be provided.
-trusttype Type of the truststore used. The default type is jks. As long as the used truststore is of type jks, you do not have to provide this parameter.
-keystore Name of the keystore file containing client certificates required for establishing an SSL connection with a server that requires client certificate authentication. If no keystore is provided, the XML client will use the default Java cacerts keystore.
-keypwd Password required for accessing the keystore. If the default Java cacerts keystore is used, no key password needs to be provided.
-keytype Type of the used keystore. The default type is jks. If the used keystore is of type jks, you do not have to provide this parameter.
-protocol Specify the protocol, for example SSL, SSLv1, SSLv3, or TLS . Note that we can select only protocols that WAS supports and has enabled. The parameter is evaluated only if the URL of the XMLAccess servlet selects a secure connection with HTTPs. Otherwise, the parameter is ignored.


Establish an SSL connection using WAS default certificate stores

xmlaccess.sh -user wpsadmin 
             -password your_password 
             -url https://portalhost:10035/wps/config/
             -in $PortalHome/doc/xml-samples/ExportAllUsers.xml 
             -out result.xml
             -truststore $WP_PROFILE/etc/trust.p12 
             -trustpwd WebAS 
             -trusttype PKCS12

Use trusttype parameter with a value of PKCS12 to avoid an invalid file format error.


Establish an SSL connection using WAS dummy certificate stores 

xmlaccess.sh -user wpsadmin 
             -password your_password 
             -url https://portalhost:10035/wps/config/
             -in $PortalHome/doc/xml-samples/ExportAllUsers.xml 
             -out result.xml 
             -truststore $WP_PROFILE/etc/DummyClientTrustFile.jks 
             -trustpwd WebAS

For this example to be able to run, configure the SSL configuration in WAS using the DummyServerKeyFile.jks and the DummyServerTrustFile.jks for secure connections. The option require client authentication must not be active.


Provide a keyfile when establishing the SSL connection

If client certificate authentication is required by server, this example sends a client certificate. Only clients with the correct client certificate will be able establish a connection with WebSphere Portal.

Using client certificate authentication is required wherever the number of clients that can administer WebSphere Portal needs to be controlled. Only clients with the correct client certificate will be able establish a connection with WebSphere Portal.

When running on the Oracle Solaris platform, the default protocol handler for the hybrid IBM JDK is the Sun handler. To connect using xmlaccess.sh and the IBM JSSE2 provider, edit...

..and add an additional parameter...

...as follows:


XML Syntax for exporting and importing credential vault data

When using the XML command line client for credential export, the command syntax is slightly different than normal command line client use because there are two additional parameters: 

xmlaccess -user user_ID 
          -password password 
          -url https://myhost:10035/wps/config/ 
          -truststore WP_PROFILE/config/cells/cellname/nodes/nodename/trust.p12 
          -trusttype PKCS12 
          -trustpwd WebAS 
          -in input_file.xml 
          -out result_file.xml 
          -credentialexport 
          -passphrase encryptionPassphrase

The following rules apply to these parameters:

  1. The options credentialexport and passphrase are mandatary for export or import of encrypted credential secrets.

    For example, during migration specify these options.

  2. The options credentialexport and passphrase are optional for all XML Configuration actions that do not export or import encrypted credential secrets during migration.

Before running the xmlaccess command, add the following properties to the WAS configuration.

  1. Log in to the WAS admin console.

  2. Click...

      Resources | Resource Environment | Resource Environment | Providers | WP_VaultService | Custom properties

    ...and add properties...

      Name Value java.lang.string
      export.userDN
      administrator_DN       		cn=wpsadmin,o=ibm java.lang.String
      export.enforceSSL true java.lang.Boolean

  3. Save your configuration changes and restart the portal server.

Element Description
-credentialexport Enable the export of credentials
-passphrase Specify the encryptionPassPhrase for the encryption. The minimum length of this string is the number of bits set as export keylength in the portal WP Credential Vault Service custom property...

    WP_VaultService / 8
The -passphrase value is used to create a key of the specified length for the encryption.

Examples: Export/import credential secrets using HTTPS:

Use the same passphrase for both export and import

The import may fail if the user DN schema has been changed between the previous and the current system or when credentials for users are contained in the xml file that are not present in the current system. In this case, manually remove the obsolete credential entries from the XML file before executing the import

For security reasons use an HTTPS connection when importing credentials; however, if you choose not to, set the export.enforceSSL configuration property to false.


Related

  1. Work with static pages
  2. Sample XML configuration files
  3. Virtual portals
  4. ReleaseBuilder
  5. Administer managed pages
  6. Portal administration tools
  7. Portal administration portlets
  8. Portal Scripting Interface
  9. Changes to xmlaccess.sh for this version of portal
  10. Sample XML configuration files
  11. Administer tags and ratings
  12. Administer analytics tags
  13. Users and groups
  14. Delayed cleanup of deleted portal pages
  15. Set service configuration properties
  16. Portal configuration services
  17. Consuming WSRP services in a Consumer portal
  18. Work with Producer definitions
  19. Changes to xmlaccess.sh
  20. Technotes for XML access and Release Builder