BACK

 

WebSphere Portal V6 Enterprise Scale Deployment

 

+

Search Tips   |   Advanced Search

 

  1. Move between environments
  2. Example deployment
  3. Transferring Portal artifacts using xmlaccess
  4. Move a differential release using ReleaseBuilder
  5. A step by step guide to moving a release between environments
  6. Configuration maintenance tasks
  7. Troubleshooting

 

Move between environments

Migration Move and convert Portal artifacts and configurations from a previous version of Portal to the current one. See...

Best Practices for Migrating to IBM WebSphere Portal 6

Migration is commonly but incorrectly used interchangeably with terms such as configuration management.

Configuration management Move a portal release to the next environment in the chain. Other terms: Elevation, Promotion, Release, Uplift and Deployment.
Release Complete portal configuration, including content and code, perfected and tested at a point in time and ready to be moved to the next server in the cycle.
Staging Process of building the final, tested release in an environment other than production with the intention of deploying that release to production. This environment is commonly called the staging environment. It gives you and the testing team the opportunity to see what the portal will look like in production before you release it to the customers or employees.

 

Example deployment

  1. A developer implements portlets, servlets, Enterprise JavaBeans, and other J2EE artifacts.

  2. A designer creates themes, skins, HTML pages, portlet JSPs, and other design elements.

  3. An administrator creates the content tree (labels, URLs, and pages) using the Portal admin user interface.

  4. Content trees and portlet instances are exported using xmlaccess.

  5. The release manager executes scripts (for example, ANT) to extract J2EE artifacts, design elements, and configurations from the version control system and then runs a build (compile and package).

  6. The operator takes delivery and deploys it onto the staging and production systems. The operator executes ready made config tasks, for example...

    • ANT
    • xmlaccess configurations
    • ReleaseBuilder
    • wsadmin scripts

There are many tools provided to help you perform these tasks. This guide will focus on four:

  • xmlaccess
  • ReleaseBuilder
  • SLChecker
  • cleanup scheduler task

All of the tasks discussed in this chapter can be automated using scripting tools such as ANT or Maven. This chapter is intended to cover the steps an administrator would perform manually if the deployment was not scripted for automation.

 

Object IDs

An object ID uniquely identifies portal resources. Object IDs are generated on resource creation. Object IDs are globally unique. Two object IDs that were automatically generated by different Portal installations can never be the same.

We can exchange resources between different Portal installations using XML exports and imports without worrying about possible object ID conflicts. Object IDs are represented by the objectid attribute in an XML export.

Object IDs are used to express references from one resource to another. For example, the following example references a portlet and puts it on a page using a symbolic object id: 

<portlet action="update" 
... 
objectid="_3_609EVJDBI1S5CD0I_97 MyPortlet" 
...>

<portletinstance action="update" 
... 
portletref="_3_609EVJDBI1S5CD0I_97 MyPortlet" 
...>

We cannot simply invent Object IDs for new resources, because they must confrm to a correct internal representation. To specify your own unique identifiers for portal resources, use Custom Unique Names.

 

Custom Unique Names

A resource that has an object id can optionally also have a unique name. Use the unique name to identify the resource unambiguously. Unique names are useful if we need a symbolic way to identify certain resources.

In contrast to object IDs, it is possible to modify unique names of resources, which may be an advantage in certain situations. Meaningful unique names are necessary to implement any scripting automation of the deployment process.

If you execute an XML import that assigns a unique name which is already used on the system, the execution fails. We can delete the unique name for a resource by setting it to the undefined value. To set a unique name for a resource, use the Custom Unique Names portlet under Administration, Portal Settings. Before you export with the xmlaccess tool, ensure that you have defined naming conventions for unique names to prevent name clashes.

Assign unique names as early as possible in the release cycle, preferably in development. Administrators may not see the need to assign unique names to all portal resources in the beginning, especially in early development, but a more thoroughly defined unique name practice will give maximum flexibility for future upgrades and migration.

For example, for one portlet WAR containing multiple portlet applications, the initial deployment.xml doesn't need a unique name for the individual portlet application. Specifying a unique name for the WAR module is sufficient for deployment. But if later on there is a need to update just one portlet application (for example, changing initial portlet configuration), you will have to update the entire WAR module since the unique name is defined only at the WAR module level.

 

The XML Configuration Interface

xmlaccess is the portal utility tool for administrators to export portal configurations and artifacts from the source server (Integration or Staging) for import into the destination server (Staging or Production). xmlaccess will not generate delete instructions for you, although we can create them by hand if you are very familiar with the structure of the XML files.

For complete differential releases between servers, use ReleaseBuilder

 

Using the xmlaccess tool for moving

Although there is no automated method to move Portal applications from one environment to another, there are two options:

  • Completely replace the old release with a new release. The drawbacks of this option is that any data that was customized by the user is lost. While this option works, you do not recommend it.

  • Use the xmlaccess tool in combination with ReleaseBuilder to load incremental or differential releases.

The XML configuration interface is more commonly referred to as the xmlaccess tool, because xmlaccess is the command that is executed. The tool provides a batch processing interface for Portal configuration updates and allows you to export an entire Portal configuration or parts of a configuration. For example, we can process and export specific pages to an XML file. We can then re-create the exported configuration from a file on another Portal.

While xmlaccess is a simplified bulk transfer utility, there is no magic button that automatically moves all the components of the Portal to the next environment. The xmlaccess tool interface was developed in WebSphere Portal V2 to help customers move Portal artifacts from one machine to another.

The xmlaccess tool is best for the initial loading of Portal application and for doing incremental releases. However, it is increasingly being used as a command line Portal administration tool. When combined with ReleaseBuilder, it can be the administrator's primary tool for migrating portal configurations between environments.

The major benefit of xmlaccess is its ability to update complete configurations of pages, portlets along with their security and configuration settings, without losing user customization. It allows you to set up the complete portal solution, and move it in its entirety to the next server in the release cycle, minimizing the possibility of human error. You also have the ability to export just part of a portal configuration - just a page, just a portlet, or an entire subtree of the portal navigaion with all the pages and portlets below it. If you perform the updates via xmlaccess, any user customization to a page or a portlet is retained because the object IDs are retained.

When exporting and importing via the xmlaccess tool, the object IDs of the portlet application are maintained. When a user customizes a portlet or a page, these customizations are stored in the back-end database. All these customizations are stored relative to the actual portlet application. The key that ties all of these customized versions of a portlet or page back to its parent is the object id.

 

ReleaseBuilder

ReleaseBuilder enables management of release configurations independent of user configurations. Release configuration data can be exported into an XML configuration interface configuration file. During staging of follow-on releases it is now possible to stage release configurations between two releases using the XML configuration interface. This allows you to track which configuration entities were removed, added or changed compared to the previous release, and apply differential updates. Differential updates are created by detecting the differences between one configuration and another. A third configuration can then be generated to represent the difference and used to apply not only addition and update modifications, but also deletions to the production server. This allows the staging and production servers to remain in synch and eliminates the problem of configuration bloat on the production server.

Like xmlaccess, ReleaseBuilder also allows you to move complete configurations from one environment to another, but we cannot use it to move partial configurations. Where it really makes a difference is in the later environments of the release cycle - Peformance testing, Staging, Production. You may not want to use ReleaseBuilder to move configurations from the development environment into QA, for example, as the development environment may not always be in a state that you want to move to other environments, especially production. A common practice is to use xmlaccess to move partial configurations from Dev to the early testing environments, and then use ReleaseBuilder to move full configurations up from there through the rest of the environments in the release cycle.

 

Transferring Portal artifacts using xmlaccess

The process of moving Portal artifacts from one environment to another is a repeatable process that, once you complete it, we can effectively duplicate the process to transfer onto subsequent environments. The exception is a clustered environment where the export process remains the same but the import process requires extra steps.

We can transfer the following using the xmlaccess tool:

  • Applications
  • Skin definitions
  • Theme definitions
  • Portlet configurations
  • Site map
  • URL mappings
  • Supported Languages
  • User resources

 

How xmlaccess works

The xmlaccess command line client is a small separate program that connects to the server using an HTTP connection, which allows you to configure the Portal remotely. The xmlaccess command is located in the wp root/bin directory of the Portal server and is xmlaccess.bat (on Windows) or xmlaccess.sh.

The syntax for the command is as follows:

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

In the command line, use the following file names:

file.xml The name of a file containing the XML request (configuration export or update) that should be processed.
result.xml The name of the result file containing the XML output (configuration export). We can later use that file to re-import the exported configuration.
url The URL to access the Portal configuration servlet. This URL consists of the Portal host name, the base Uniform Resource Identifier for the Portal, as specified during installation (for example /wps), and the servlet extension /config. Use the xmlaccess tool to transfer a complete configuration, including:

For virtual portals, use...

    wps/config/VP_portal_name

You need to transfer portlet *.war files separately. Copy *.war files to...

PortalServer/installableApps/

...on the target server. Themes and skins also need to be deployed separately, although they are defined and assigned to pages using xmlaccess.

With the xmlaccess tool, we can also:

  • Load the WebSphere Portal default portlets configuration during the initial install and transfer parts of Portal configuration.

  • Create and modify existing Portal artifacts in incremental releases.

  • Delete Portal artifacts. However, manually add delete commands to the input file.

 

Transfer process

Transferring the Portal artifacts from one environment to another requires you to export the artifacts from the source environment and then transfer those artifacts to the target environment when import them.

The process involves the following steps:

  1. Export the source configuration using xmlaccess commands.
  2. Bundling the supporting files from the source Portal.
  3. Transferring the bundled files to the target Portal.
  4. Distributing the supporting files to the correct locations on the target Portal.
  5. Updating the configuration of the target Portal using the xmlaccess tool.
  6. Following up with post-transfer activities.

 

Export a sample page using xmlaccess

There a number of sample scripts available from the WebSphere Portal InfoCenter. In the following example, you modified the sample file ExportPage.xml to export the Portal Welcome Page.

  1. Copy and paste the following sample into a text editor and save it as ExportPage.xml. 
    <?xml version="1.0" encoding="UTF-8"?> 

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

    <portal action="
        locate">

      <content-node action="export" 
        uniquename="wps.My Portal.Welcome"/> 

    </portal> 

</request>

  2. Run xmlaccess against this export script. For example...

    cd WebSphere/PortalServer/bin
    ./xmlaccess.sh -user wpsadmin -pwd wpsadmin -url http://amsterdam.setgetweb.com:10038/wps/config -in ExportWelcomePage.xml -out ExportedWelcomePage.xml

Regardless of whether the XML export works correctly, you will see an output file called ExportedWelcomePage.xml. If you open this file, the last line should display...

<status element="all" result="ok" />

If it the export was unsuccessful, a error message appears to tell you what went wrong with the export.

 

Export and import a new page

To move a custom page from a staging to production environment, we can export and then import the page from one Portal into another. In a staging or production environment...

  1. Create a new blank page in the Portal.

  2. Assign the blank page a unique name. You assign unique names to a Page via the Portal Administrative interface by selecting...

    Portal Settings | Custom Unique Names | Pages | pagename

    and assigning the page a meaningful custom unique name, such as my.TestPage.

  3. Do not add any portlets to this page.

  4. Create an xmlaccess input file and set the uniquename attribute of the page to export to the unique name.

  5. Ensure that the -out parameter in the command line points to a new export file, for example ExportedTestPage.xml For example...

    c:\WebSphere\PortalServer\bin\xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://amsterdam.setgetweb.com:9081/wps/config -in ExportTestPage.xml -out ExportedTestPage.xml

  6. Run the export and ensure that you see the status...

    element="all" result="ok"/

    ...at the end of ExportedTestPage.xml.

 

Transferring

To transfer the file, copy (or FTP) the exported XML file (ExportedTestPage.xml) to the Production Portal Environment.

 

Importing

To import the file:

  1. Prepare the xmlaccess import. The import is basically the same as the export except that you pass the exported output from the staging environment as the input for the production environment.

    The xmlaccess input command line on UNIX may look like this:

    /WebSphere/PortalServer/bin/xmlaccess.sh -user wpsadmin -pwd wpsadmin -url http://aixportal1.redbook.ibm.com:9081/wps/config -in ExportedTestPage.xml -out Results_ExportedTestPage.xml

  2. Check the XML results by opening Results_ExportedTestPage.xml and check for the message...

    <status element="all" result="ok"/>

    You may see warnings that the users and groups could not be retrieved from the Portal datastore if the LDAP environments are different between the staging and production environments.

  3. Check that the page has been imported correctly by accessing the page in the Portal user interface via a Web browser.

 

Move a differential release using ReleaseBuilder

ReleaseBuilder is the portal utility tool for administrators to manage and maintain their xmlaccess xml files for each release. Before ReleaseBuilder, administrators were faced with a choice of much work using cut-and-paste, merging multiple export files and creating instructions to delete pages by hand, or wiping out the production environment and doing a full import with each release cycle. The first option exposed serious risk of human error, the second requires significant downtime of the portal. ReleaseBuilder simplifies the process, by automating the task of finding the differences between the old release and the new. The resulting XML file then contains only the differences between the two configurations.

 

ReleaseBuilder process overview

For the first release, you run a full xmlaccess export and import it into the empty Production portal.

For subsequent releases, you will use ReleaseBuilder to automate the handling of the xmlaccess files.

  1. Take a full export of the Staging environment.

  2. Take a full export from the Production environment (which was originally configured from a full export of the staging environment), or use the previous release file, which should be in the version control system.

  3. Use ReleaseBuilder to create the differential xml file.

The resulting xml file will contain only the differences between the environments. New pages and portlets will be in the file, as well as changes to existing pages or portlets, and the file will also contain instructions to delete artifacts that no longer exist in the new release.

Once you have produced the differential XML file with ReleaseBuilder, we can then copy updated WAR files, themes and skins and import the configuration into Production. ReleaseBuilder will detect whether or not WAR files have been updated, and remove or leave in the <URL> tag pointing to the WAR file as necessary. You still need to copy the updated WAR file to a location that can be reached from the server that you will be running the import from, and edit the <URL> tag if necessary to point to the updated file.

 

Using the ReleaseBuilder tool

ReleaseBuilder is the portal utility tool for administrators to manage and maintain their xmlaccess xml files for each release. The syntax for the command is as follows:

releasebuilder.sh -inOld FullRelease0.xml -inNew FullRelease1.xml -out Release1.xml

On the command line, use the following values:

inOld A full xmlaccess export of the old configuration
inNew A full xmlaccess export of the new configuration
out Release file

The output of the ReleaseBuilder file is an xmlaccess file containing the difference between the old and new configurations and is used to apply not only addition and update modifications, but also deletions to the production server. This allows the staging and production servers to remain in synch and eliminates the problem of configuration bloat on the production server.

For performance reasons, IBM recommends that ReleaseBuilder be run on a separate, standalone machine. This system can be the staging system, or a completely separate system on which WebSphere Portal is installed. To maximize use of system resources, WebSphere Portal should not be running during ReleaseBuilder execution.

 

Preparing to build a release

If you already have an existing production system, but without a defined configuration management scheme in place, this is how you take control:

 

Export the current production configuration

Use xmlaccess to do a full xmlaccess export from the production server.

cd WebSphere/PortalServer/bin/
./xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://production.portal.ibm.com:9081/wps/config -in ExportRelease.xml -out ExportedProdRelease.xml

ExportRelease.xml is found under PortalServer/doc/xml-samples

 

Prepare the staging environment

If you haven't built the Staging environment yet, do the install with the flag set to install an empty portal. This environment doesn't necessarily have to be the "Stage" environment. It should be the lowest environment that you want to keep under Configuration Management control, which might be development.

./install.sh -W emptyPortal.active="True"

If you have an existing Staging environment with configurations in it already, empty it by running the empty portal task:

WPSconfig.sh action-empty-portal

 

Import the production configuration into the staging environment

Use xmlaccess to import the production configuration into the now-empty staging environment:

cd WebSphere/PortalServer/bin
./xmlaccess.bat -user wpsadmin -pwd wpsadmin -url http://staging.portal.ibm.com:9081/wps/config -in ExportedProdRelease.xml -out ExportedProdRelease.out

Now the two environments have the same configuration, right down to the object ids. If you have content ready in the development environment, you may use xmlaccess to transfer it, or we can use the Portal Administrative portlets to set up the staging environment for the next release to production.

 

A step by step guide to moving a release between environments

In this section, you will lay out, in a step by step fashion, all of the tasks needed to export the portal release from one environment, and import it into another. In this example, you will assume that you are ready to move Release1 from the staging environment to the production environment, which contains configurations and content from Release0. If the production environment has been installed with the option for an Empty Portal, simply skip the steps for exporting the release information from the Production environment and building the differential release XML file.

     

  1. Prepare Source Environment

    2. Before you export or import Portal configurations, prepare the transfer environment to reduce the chances of mistakes and to ensure that the Protal artifacts and configuration information are exported to an identifiable location. Preparing the environments is not strictly required, but it is a best practice that you find works in a larger Portal deployment. Preparing the environment allows you to identify when artifacts were exported, so that we can revert back to the original files if needed.

       

    • Set up transfer directory

      • Create directories...

      mkdir PROFILE_HOME/transfer
      mkdir PROFILE_HOME/transfer/mmddyy
      mkdir PROFILE_HOME/transfer/config

      Copy...

      PORTAL_HOME/PortalServer/doc/xml-samples/ExportRelease.xml

      ...to...

      PROFILE_HOME/transfer/config

      Create export.sh script...

      cd /opt/WebSphere/PortalServer/bin
      ./xmlaccess.sh -url http://setgetweb.com:10044/wps/config -user wpsadmin -pwd wpsadmin -in $* -out exported_$*
      tail -n 3 exported_$*

    • Create import script...

      cd /opt/WebSphere/PortalServer/bin/
      ./xmlaccess.sh -url http://setgetweb.com:10044/wps/config -user wpsadmin -pwd wpsadmin -in $* -out $*.out
      tail -n 3 $*.out

     

  2. Assign Custom Unique Names

    3. Assign custom unique names to pages and portlets. Your organization should have a defined naming standard for all Portal artifacts.


    		Default Install HR Accounting
    Pages wps.PageName HR.pageName Acc.pageName
    Portlet applications None HR.portletName Acc.portletName
    Portlets None HR.Portlet Acc.Portlet
    URL mapping context NA HR.Url1 Acc.Url2
    User groups None HR.GroupName Acc.GroupName
    Web modules None HR.AppName Acc.AppName
    Skins wps.skin.skinName HR.skin.skinName Acc.skin.skinName
    Themes wps.theme.themeName HR.theme.themeName Acc.theme.themeName

    We cannot assign unique names to themes or skins via the Portal Administration Interface. However, we can assign them using the xmlaccess tool. There is a sample file called DeployTheme.xml available to help you set custom unique names for the themes and skins.

    To set a custom unique name for the themes and skins, create the file ExportThemesAndSkins.xml in the transfer/config directory as follows:

    ExportThemesAndSkins.xml 

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

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

<portal action="locate"> 

    <skin action="export" objectid="*" /> 

    <theme action="export" objectid="*" /> 

</portal> </request>

    Open a command prompt in the directory representing today's date. Run the command export.bat ExportThemesAndSkins.xml. This should result in a file called exported_ExportThemesAndSkins.xml that looks something like the following example:

    Output of ExportThemesAndSkins.xml 

    <?xml version="1.0" encoding="UTF-8"?>
<!-- IBM WebSphere Portal/6.0 build wp600_244 -->
<!-- 1 [skin K_NO2UF4I1186E1026H4BLVI00E6] -->
<!-- 2 [skin K_NO2UF4I1186E1026H4BLVI00E1] -->
<!-- 3 [skin K_NO2UF4I1186E1026H4BLVI00E5] -->
<!-- 4 [skin K_NO2UF4I1186E1026H4BLVI00E3] -->
<!-- 5 [skin J_8000CB1A08VRD02EETLAMB0004] -->
<!-- 6 [theme J_NO2UF4I1186E1026H4BLVI00E7] -->
<!-- 7 [theme J_8000CB1A08VRD02EETLAMB0000] -->

<request 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" build="wp600_244" 
        type="update" 
        version="6.0.0.0" 
        xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">

 <portal action="locate">

  <skin action="update" 
         active="true" 
         default="true" 
         domain="rel" 

         objectid="K_NO2" 
             resourceroot="IBM" 
             type="default" 
             uniquename="ibm.portal.skin.IBM">

  <localedata locale="en">   
  <title>IBM</title>   
  <description>
  </description>

  </localedata>

  ...  </skin>  
  <skin action="update" 
               active="true" 
               default="false" 
               domain="rel" 

objectid="K_NO2" 
               resourceroot="ThinSkin" 
               type="default" 
               uniquename="wps.skin.thinSkin">

  <localedata locale="en">   
  <title>Thin Skin   </title>   
  <description>
  </description>

  
  </localedata>  
  </skin>  

  <skin 
      action="update" 
      active="true" 
      default="false" 
      domain="rel" 

objectid="K_NO2" 
               resourceroot="NoSkin" 
               type="default" 
               uniquename="wps.skin.noSkin">

  
  <localedata locale="en">   
  <title>NoSkin </title>   
  <description>
  </description>

  
  </localedata>

  ...  
  </skin>  
  <skin action="update" 
          active="true" 
          default="false" 
          domain="rel" 

objectid="K_NO2" 
          resourceroot="IFrame" 
          type="default" 
          uniquename="wps.iframe.album">

  
  <localedata locale="en">   
  <title>IFrame </title>   
  <description>
  </description>

  
  </localedata>

  ...  
  </skin>  
  <skin action="update" 
          active="true" 
          default="false" 
          domain="rel" 

objectid="J_800" 
          resourceroot="MySkin" 
          type="default" 
          uniquename="undefined">

  
  <localedata locale="en">   
  <title>MySkin   </title>   
  <description>
  </description>

  </localedata>  
  </skin>  
  <theme action="update" 
           active="true" default="true" 
           defaultskinref="K_NO2UF4I1186E1026H4BLVI00E6" 
           domain="rel" 
           objectid="J_NO2" 
           resourceroot="IBM" 
           uniquename="ibm.portal.theme.IBM">

  
  <localedata locale="en">   
  <title>IBM
  </title>   
  <description>
  </description>

  
  </localedata> 

  ...  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E1" update="set"/>  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E5" update="set"/>  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E6" update="set"/>

  
  </theme>

  
  <theme action="update" 
           active="true" 
           default="false" 
           defaultskinref="K_NO2UF4I1186E1026H4BLVI00E6" 
           domain="rel" 
           objectid="J_800" 
           resourceroot="MyTheme" 
           uniquename="undefined">

  
  <localedata locale="en">

   
  <title>MyTheme   </title>  
  </localedata>  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E1" update="set"/>  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E3" update="set"/>  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E5" update="set"/>  
  <allowed-skin skin="K_NO2UF4I1186E1026H4BLVI00E6" update="set"/>

  
  </theme> 
  </portal> 
  <status element="all" result="ok"/>


  </request>

    Your export will contain several more localedata stanzas for the default languages supported by WebSphere Portal Server, but for brevity, I have stripped out all but the english ones. Notice the theme and skin "MySkin" and "MyTheme" which both have a uniquename assignment of "undefined". This is what you want to change.

    SetUniqueNames.xml: 

    <?xml version="1.0" encoding="UTF-8"?>
<request 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd"              
                 type="update" 
                 create-oids="false">

    <portal action="locate">  
        <skin action="update" 
               objectid="J_800" 
               uniquename="my.MySkin"/>  
        <theme action="update" 
               objectid="J_800" 
               uniquename="my.MyTheme"/> 
    </portal> 

</request>

    For this example you pulled the objectid references from the previous export to reference the theme and skin definition that you want to assign the custom unique names to. Notice that create-oids has been set to false. If you leave this value at true, xmlaccess will reference ObjectIds as internal references while processing the script, but create a new instance of a theme and skin with a new ObjectId and the custom unique names you want to use, but without the resource root or other configuration information.

    With custom unique names, we can avoid running through this excercise again. Run this file using the command...

    import.bat SetUniqueNames.xml

    The output will be created in file SetUniqueNames.xml.out, and should look like the following: 

    <!-- 1 [theme J_8000CB1A08VRD02EETLAMB0004 uniquename=my.MySkin] -->
<!-- 2 [theme J_8000CB1A08VRD02EETLAMB0000 uniquename=my.MyTheme] -->
<request 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         build="wp600_244" 
         type="update" 
         version="6.0.0.0" 
         xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd">

 <status element="all" result="ok"/> 


    </request>

    To create themes and skins directly using xmlaccess... 

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

<request 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" build="wp600_244" 
         type="update" 
         version="6.0.0.0" 
         xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd" 
         create-oids="true">

    <portal action="locate">  

        <skin action="update" 
              active="true" 
              default="false" 
              domain="rel" 
              objectid="myskin-oid" 
              resourceroot="MySkin" 
              type="default" 
              uniquename="my.MySkin">
    
              <localedata locale="en">   
                  <title>MySkin</title>   
                  <description> </description>
              </localedata>  
        </skin>  

        <theme action="update" 
               active="true" 
               default="false" 
               defaultskinref="myskin" 
               domain="rel" 
               resourceroot="MyTheme" 
               uniquename="my.MyTheme">  
    
            <localedata locale="en">
                <title>MyTheme</title>  
            </localedata>  
    
            <allowed-skin skin="myskin-oid" update="set"/>
        </theme> 

    </portal> 

</request>

    Notice, in this case, you have set create-oids to true, so that we can use an internal reference to assign the new skin to the new theme, neither one of which has an ObjectId assigned to it yet.

     

  3. Gather required files

    4. Run build from the version control system of all portlet *.war files and place them in the transfer directory with today's date. If you have any new or changed themes and skins, place them in the directory also. Check the entire contents of this directory into version control as the release.

     

  4. Build the release

    5. Now that you have set up a working environment on the source servers and set up custom unique names, you are ready to start building the release.

       

    • Export new release from the source server

      • You should have copied the ExportRelease.xml file from...

      PortalServer/docs/xml-samples

      ...as part of the preparing the environment excercise. From the transfer directory representing today's date, run the following command:

      ../export.sh ExportRelease.xml

      This will create an exported_ExportRelease.xml file in the current directory. If you have an exported_ExportRelease.xml file from the previous release that is currently running on the target server, you may skip the next section. If there is nothing in the target server that you wish to keep (i.e. the target server is empty or a new, default configuration from the install process), perform the steps in the next section to make sure that releases will be consistent going forward.

       

    • Obtain previous release data

      • If you still have the xmlaccess file stored in the version control system that was used for the initial Portal deployment, and have not made any configuration changes through xmlaccess or the portal Admin GUI, you may reuse that file for this step. Otherwise, obtain an xmlaccess export of the current configuration as follows:

      If it doesn't already exist, set up the same transfer directory structure on the target server as in section 7.5.1, "Prepare Source Environment". Create the current date directory representing the date that the current release data was placed into production, NOT today's date. Run the ExportRelease.xml script as in section 7.5.2, "Build the release" from that directory.

      Copy the release date directory that now contains an exported_ExportRelease.xml file over to the source server on which you will run ReleaseBuilder.

       

    • Run Release Builder

      • From the transfer directory, run the following command:

      ../bin/releasebuilder.sh -inNew todays_release_dir/exported_ExportRelease.xml -inOld previous_release_dir/exported_ExportRelease.xml -out todays_release_dir/Release.xml

      In the example, the todays_release_dir was 10232006 and previous_release_dir was 10022006. This will create the file necessary to duplicate the configuration from the source server on the target server.

      It is not recommended that you run the ReleaseBuilder task on the Production server. Depending on the configuration, it may consume significant CPU and memory resources and have an adverse impact on system performance. Run ReleaseBuilder on a development or integration servers or on a machine specifically dedicated for this purpose.

     

  5. Prepare the target environment

    6. If you are using WCM or Personalization, and you did an empty portal install on the target server, configure them before we can run a successful import.

       

    • Create transfer directory

      • If it doesn't already exist, set up the same transfer directory structure on the target server as found on the source server. Create the current date directory representing today's date and run the ExportRelease.xml script from that directory.

       

    • Copy the files to target server

      • Move the entire directory over to the target server.

      Copy all portlet WAR files into the PortalServer/installableApps directory.

      Modify the Release1.xml file to change all url tags to point to the installableApps directory instead of the deployed/archive directory.

       

    • Deploy themes and skins

      • If you have made changes to themes and skins that need to be included in this release, deploy them into the target environment before running xmlaccess. As this will require a portal application restart, it should be done during a scheduled outage.

     

  6. Import the release into the target server

    7. If you have updated themes, skins or screens, deploy them to the server. From the current date directory on the target server, run the following command:

    ../Import.sh Release.xml

     

  7. Post transfer actions

    8. If you are deploying into a clustered environment, any updated portlets can't be activated until the updated code has been synchronized down to all the nodes. Perform the following task from the portal_server_root/config directory to synchronize the changes across cluster members and to activate all the portlets:

    ./WPSconfig.sh activate-portlets

    If any portlets have custom configurations that are different between development, test, and staging environments and the production environment - for example, URLs pointing to the development instance that need to be changed to the production instance. If you have a lot of these kinds of configurations that need to be changed, you really should consider either pulling these from properties files on the filesystem of the respective environments, or scripting deployments.

 

Configuration maintenance tasks

 

Handling orphan data

When portal resources are deleted, dependent resources that are stored in a different database domain are not deleted at the same time. These remaining resources are still available for backup scenarios or other production lines that might share the database domain. For example, when an administrator deletes pages, the user customization to the deleted pages are not deleted. The SLCheckerTool allows you to detect orphaned data that is not needed any more by any of the production lines that share the domain. Use the SLCheckerTool to prepare an XML script for later deletion of the orphaned data by the XML configuration interface.

The SLCheckerTool is included in the file wp.db.slchecker.jar in the following directory:

    portal_server_root/bin

Invoke the SLCheckerTool by using the following shell scripts:

    ./slcheckertool.sh

To prepare and complete deleting orphaned data you also perform some steps by using the XML configuration interface. For details about the XML configuration interface refer to 7.2.3, "The XML Configuration Interface" The XML configuration interface. For details about how to use the XML configuration interface refer to , "Using the xmlaccess tool for moving" Working with the XML configuration interface. A sample XML script ExportIncludingOrphanedData.xml can be found under PortalServer/doc/xml-samples which allows you to prepare the orphaned data for work with the SLCheckerTool.

Before deleting the orphaned data by using the SLCheckerTool, secure databases by making a backup.

To delete all orphaned data, include every production line that shares the database domain. Otherwise resources that are still valid in a skipped production line might be unintentionally removed.

To delete the orphaned data, proceed by the following steps. For each step, use the target file from the previous step as the source file.

Create a full export including orphaned data of each production line that shares the particular domain. To do this, use the XML configuration interface and the XML sample file ExportIncludingOrphanedData.xml.

Use the SLCheckerTool to create an XML script file to delete the orphaned data. To do this, proceed by the steps given below. Observe the following rules:

For each step, start the SLCheckerTool with the appropriate parameters as described under that step.

Replace all file name variables (given in italics) by the complete directory path location and file name.

For each step, use the target file(s) from the previous step as the source file(s).

Invoke the SLCheckerTool by using the following shell scripts:

./slcheckertool.sh

Find candidates for orphaned data in each production line. Repeat this step for each production line, but specify a different output file for each iteration, otherwise the results will be overwritten. Use the following parameters:

[SLCheckerCmd] -find-candidates -s xml_source_file -d cand_target_file -domain domain_identifier

Use these parameters to find the candidates for orphaned data within one production line. Replace the variables as follows:

    table cellpadding=10 border=1> xml_source_file Full XML export file that you created in the step for creating the XML export including orphaned data. cand_target_file Target file. The orphaned data candidates will be saved to that file. domain_identifier Database domain in which you want candidates to be searched. Valid values are...

    • comm for the community database domain
    • cust for the customization database domain
    • all for both database domains.

Identify the orphaned data. Perform this step only once, but with all the candidate files generated by previous step at once, as this step determines the intersection of all result files, that is, the data that are orphaned in all production lines. Use the following parameters:

[SLCheckerCmd]-identify-orphans -s cand_source_files_and_directories -d orph_target_file

Use these parameters to identify the orphaned data by matching the information from all the candidate files. Replace the variables as follows:

    cand_source_files_and_directories Specify all files that were generated as cand_target_files by the substep for finding the candidates. If you specify one or more directories with the files, verify these directories contain only candidate files and no other files.
    orph_target_file Specify the target file. The identified orphaned data will be saved to that file.

Generate an XML script file. We can later use that script for deleting the orphaned data. Use the following parameters:

    SLCheckerCmd -delete-orphans -s orph_source_file -d xml_target_file

Use these parameters to generate an XML script file for deleting the orphaned data. Replace the variables as follows:

    orph_source_file Specify the file that was generated as the orph_target_file in the step for identifying the orphaned data.
    xml_target_file Specify the target file. This will be the XML script file that contains the information about the orphaned data. We can later use this file to delete the orphaned data.

We can check whether all production lines were considered during the creation of the XML script file. To do this, review the comment in the file header. The header contains information about all full exports that were used.

Delete the orphaned data. To do this, invoke the the import command that you created with the XML script that you obtained as the xml_target_file with the orphaned data in the step for generating the XML script. You need to invoke the XML configuration interface with the XML script only on one production line that shares the database domain. This will delete the orphaned data for all production lines that share that database domain...

./import.sh xml_target_file

...or...

/WebSphere/PortalServer/bin/xmlaccess.sh -user wpsadmin -pwd itso -url http://aixportal1.redbook.ibm.com:9081/wps/config -in xml_target_file -out DeleteOrphanResults.xml

You have removed all orphaned data from the portal database.

Delayed cleanup of deleted portal resources

A new performance enhancement in Portal 6.0 that was introduced in 5.1 is the delayed cleanup of portal resources. When portal resources such as pages, components or portlet instances are deleted from the portal server, the actual deletion can take a considerable amount of time and have a noticeable performance impact on the portal. Therefore, the actual deletion is scheduled for a later time. We can configure the frequency or disable this feature using the configuration interface. In a test or staging environment disable this completely for administrative convenience. Leave it enabled in production for performance reasons.

To run the cleanup task immediately...

Copy the file Task.xml from PortalServer/doc/xml-samples or create a new file with the following contents:

Example 7-10 xmlaccess file to perform immediate cleanup of portal resources 

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


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

    <portal action="locate"> 

<task action="create" bean="ejb/wpsSchedulerTask"/> 
</portal> 
</request>

Run the command using xmlaccess:

cd /WebSphere/PortalServer/bin
./xmlaccess.sh -user wpsadmin -pwd itso -url http://aixportal1.redbook.ibm.com:9081/wps/config -in Task.xml -out TaskResults.xml

To disable scheduled cleanup completely:

This will force immediate deletions of portal resources, and can be useful in a development or Integration environment:

If the portal is running standalone, use the local console; if the portal is installed in a cluster, use the console of the Deployment Manager.

  1. Start the administrative console by entering the following in the location bar of a Web browser:

  2. http://example.com:admin_port/ibm/console

  3. where example.com is the name of the server and admin_port is the port assigned to the administrative console.

  4. In the left frame, open the Resource section by clicking the plus ( + ) sign.

  5. Click Resource Environment Providers.

  6. If you are running a clustered environment, set the scope to the portal cluster.

  7. In the right frame, select the WP DataStoreService to which you want to make changes.

  8. Click Custom Properties.

  9. Create a new property called scheduler.cleanup.enabled and set the value to false. Use java.lang.String as its type and don't mark the property as required. Otherwise you will not be able to delete it later.

  10. When you are done, click Save at the top of the screen under Message(s).

  11. Click Save again when prompted to confirm the changes.

    If the are running WebSphere Portal in a cluster configuration, replicate the changes to the cluster. (In the Administration Console, select System Administration and then Nodes. Select all of the nodes in the cluster, and click Synchronize).

  12. Restart the portal to make the changes become effective.

This is NOT a recommended setting for a Production environment!

To alter the schedule of the cleanup service:

By its default schedule configuration, the cleanup service runs weekly, on Saturdays at 8 pm. We can specify daily, weekly or monthly cleanup at a specified time. We cannot schedule both a monthly and a weekly task, or a daily and a monthly.

Copy the file Task.xml from PortalServer/doc/xml-samples or create a new file with the following contents:

Example 7-11 xmlaccess file to alter scheduled cleanup of portal resources 

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

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


    <portal action="locate"> 

        <task action="create"  bean="ejb/wpsSchedulerTask"> 

        <dayOfMonth>31</dayOfMonth> 
        <startTime>23:59</startTime> 

    </portal> 

</request>

Run the command using xmlaccess:

cd WebSphere/PortalServer/bin
./xmlaccess.sh -user wpsadmin -pwd itso -url http://aixportal1.redbook.ibm.com:9081/wps/config -in Task.xml -out TaskResults.xml

Setting a dayOfMonth value of 31 causes the cleanup task to be done on the last day of the month, for example on February 28, September 30, or October 31.

To schedule weekly cleanup, substitute dayOfMonth for dayOfWeek where, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, 7=Sunday.

To schedule Daily cleanup, simply remove the dayOfMonth tag completely, leaving only the startTime.

 

Deploying themes and skins

This approach does not require the enabling of automatic JSP reloading and does not affect the portal's run-time performance. Because of this, it is the recommended way to deploy themes and skins in a production environment.

Before you start this task, make sure that all of the following is true:

The administrative server of the WebSphere Application Server has been started:

  • If the portal runs in a base application server node, verify the administration server is running. The default name is server1.

  • If the portal runs in a Network Deployment (ND) cell, verify the Deployment Manager (DM) and all node agents are running.

To deploy themes and skins in a production environment, proceed as follows:

  1. Export the WebSphere Portal EAR file, wps.ear, according to the network configuration. If you have a cluster environment, the WebSphere Portal EAR must be exported from the WebSphere Application Server Network Deployment machine.

      cd was_profile_root/bin
      wsadmin.sh -user admin_user_id -password admin_password -c '$AdminApp export wps /tmp/wps.ear'

  2. Use the EARExpander tool to expand the contents of the exported EAR file

      mkdir /tmp/wps_expanded
      EARExpander.sh -ear directory/wps.ear -operationDir /tmp/wps_expanded -operation expand

  3. Place the updated themes and skins JSPs into the correct directory within the expanded EAR. For example:

    • HTML themes go in...

        /tmp/wps_expanded/wps.war/themes/html

    • HTML skins go in...

        /tmp/wps_expanded/wps.war/skins/html

  4. Delete the original the wps.ear file from the directory where you initially exported it.

  5. Use the EARExpander command to collapse the EAR directory back into an EAR file:

      EARExpander.sh -ear /tmp/wps.ear -operationDir /tmp/wps_expanded -operation collapse

  6. Use the wsadmin command to update the WebSphere Portal EAR.

  7. If you have a managed cell (with or without a cluster), perform this step on the deployment manager machine.

      ./wsadmin.sh -user admin_user_id -password admin_password -c '$AdminApp install /tmp/wps.ear {-update -appname wps -nodeployejb}'

  8. Restart the wps application using the administrative console. In a managed node or cluster configuration, perform this restart using the administrative console for the deployment manager.

    • Log in to the administrative console.

    • Select...

      Applications | Enterprise Applications wps_application | Stop

    • After the application is fully stopped, click Start.

    Updates to the configuration of a cluster must occur on the deployment manager and be resynchronized with the other nodes in the cluster. If updates are made to individual nodes in the cluster, the updates will be lost when the master configuration on the deployment manager resynchronizes with the nodes again as changes on a node are overwritten. When you run configuration tasks on the nodes, however, you do initiate them on the nodes but must modify the master configuration (remote connection from the node to the deployment manager).

     

    Troubleshooting

    This section affords a few hints for discovering and solving some common issues, problems and mistakes that can occur when using xmlaccess to transfer Portal configurations between environments.

    xmlaccess imports can be an iterative adventure. There is no utility to scan the import file for invalid paths, correct syntax or missing references. The process will run and perform any actions which it understands and fail when it reaches a section it does not understand. It is not transactional, so nothing is rolled back after a failure. If you have create-oids="true" as an attribute on the request stanza, it will create additional copies of each object that it created already when you re-run the xmlaccess script, unless you manually cut out the sections that have already been performed.

     

    Problems importing portlets

    There are two common problems when working with xmlaccess to deploy and update portlets:

    • Improper path to the portlet WAR file

      xmlaccess exports XML files with paths to the WAR file for update in this Instead, it only creates pseudo-references in the form of file URLs that rely on the assumption that the file resides under the deployed/archive subdirectory of the WPS installation, as in the following example: 

      <url>
file://localhost/C:/WAS60/PortalServer/deployed/archive/com.ibm.wps.port lets.resourceview.ResourceView/ResourceView.war
</url>

      If these assumptions are not met, an exported portal configuration cannot be successfully re-created without editing the generated URLs manually. Fortunately, there are two simple solutions to this:

      1. Copy the WAR files from the deployed/archive directory on the source server to the target server.

      2. Change all the URL references in the XML import file to point to the actual locations of the files. If you wish, you may set up a web server somewhere to serve up the portlet WAR files and change the <URL> targets to use a referenceable URL instead of a file:/// tag, as in...

          http://webserver/ResourceView.war

      This could be particularly useful if you wish to be able to deploy to many different portal servers.

    • Failure to activate portlets after using xmlaccess to deploy portlets in a cluster.

      When portlets are updated in a cluster, they need to be synchronized down to the nodes from the deployment manager before they can be activated. Monitor the nodeagent log files on the cluster members to determine whether they are all synchronized, and then run the config task...

        WPSConfig.sh activate-portlets

      If you have a large number of portlets listed in the xmlaccess import file that are already installed on the target server, and you only wish to update configuration information and you don't need to redeploy the code, you may remove the entire <URL> tag from the XML file and save a significant amount of time on the xmlaccess import by not redeploying the portlet code.

     

    Problems importing pages

    If you export just pages, and not the full export, the configurations of portlets on those pages will not be exported. For example, if you export the Welcome page from the default install configuration, you will see entries such as in Example 7-12:

    Example 7-12 

    <web-app action="locate" 
         domain="rel" 
         objectid="1_NO2" 
         uid="com.ibm.wps.portlets.welcome">  

    <servlet action="locate" 
             domain="rel" 
             objectid="V_NO2" 
             referenceid="portletidwelcome"/>  
    
    <portlet-app action="locate" 
                 domain="rel" 
                 name="Welcome" 
                 objectid="2_NO2" 
                 uid="com.ibm.wps.portlets.welcome.1">   
    
    <portlet action="locate" 
                 domain="rel" 
                 name="Welcome Portlet" 
                 objectid="3_NO2" 
                 uniquename="wps.p.Welcome"/>  
    </portlet-app>  
</web-app>

    This is necessary for xmlaccess to find the portlets, but it depends on

     

    Problems importing policies

    A new feature in WP6.0 is the ability to specify and apply common and specialized settings that determine the how portal resources function for different classes of users.

    A policy is a collection of settings that influences the behavior of a portal resource and the experience that users will have when working with the resource. Policies simplify the management of portal resources because the policy settings for a resource type can control the behavior of the resource for different classes of users. For sites that comprise large numbers of users and resources, specifying and applying policies to portal resources eliminates much time-consuming effort that would otherwise require administrators to manage a vast array of discrete settings for users and resources.

    Like working with portlets, using xmlaccess to configure policies takes a little additional work on the operators part. Policy configurations are stored in a separate file, so that file must be copied over from the source server to the target server. By default, it is found in the PortalServer root directory. It can be copied over to the same directory on the target server, or we can adjust the URL referenced in the XML file to the location of the file on the target server.