Building a Release

 

Overview

ReleaseBuilder allows you to compare the XML configuration files that describe your staging server (REV1) and your updated staging server (REV2), and creates an XML configuration file that contains the differences between the two servers. This output file is then used to import only the differences from your staging server(REV2) onto the production server. Features that are unchanged from (REV1) on the staging server (REV2) are not affected.

 

Before you begin

Before you run ReleaseBuilder, ensure that your development, test, and production WebSphere Portal environments are configured to allow all of the required artifacts and the configuration to be moved.

ReleaseBuilder should preferably be run on an integration or staging server. Running ReleaseBuilder on the production server is not advised because ReleaseBuilder will consume resources and affect portal services to users.

If you have a completely new installation of the staging server and the production server:

  • Install the staging server, then install the production server
  • Develop a release on the staging server
  • Build the release on the staging server
  • Import that release onto the production server.

If you already have a production server (without a staging system):

  • Export the release of your production server.
  • Install a staging server and import the production release onto the staging server.
  • Develop and build a new release on the staging server.
  • Export that new release from the staging server.
  • Import the new release onto the production server.

 

Steps for this task

XML configuration files are used by ReleaseBuilder to create a differences XML configuration file that will be used to transfer the new portal configuration from your staging server to your production server. To export the configurations of the servers, use the XML configuration interface.

  1. For ease of use in identifying Portal objects in the XML, assign unique names to the pages, labels and URLs you create.

    Virtually all objects installed by default have unique names assigned. However, unique names for skins and themes can only be set using the XMLAccess interface. A short portion of XML, for Portal 5.0.x, that shows how to assign a unique name to a skin is provided below. Note: Portal 5.1.x uses the schema PortalConfig_1.3.xsd. 

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

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

    <portal action="locate"> 

        <skin action="update" 
                 objectid="_K_0O2QCPBSR900H588_9D MilkyWay Main Skin" 
                 uniquename="wps.skin.milkywaymainskin">
        </skin>

    </portal>
</request>

  2. Export staging server (REV1) configuration

  3. Export the entire portal configuration (not including users) of the staging server (REV1).

    1. On the staging server (REV1) change to the wp_root/bin directory. This is the directory that contains WebSphere Portal tools.

    2. Export the staging server (REV1) configuration using the XML configuration interface and the provided sample file named Export.xml: 

      ./xmlaccess.sh -in Export.xml \
               -user wpsadmin \
               -password wpsadminpwd \
               -url http://stagingserver.setgetweb.com/wps/config \
               -out stagingserverREV1_config.xml

      The exported configuration is stored in the XML file named stagingserverREV1_config.xml.

  4. Develop and test new functions and portlets on the staging server. This phase is where functions are added or deleted. Note that this phase can last for a very long time. Ensure the staging server is fully tested and the portal is ready.

  5. Export staging server (REV2) configuration

    Export the entire portal configuration (not including users) of the updated staging sever (REV2).

    1. On the staging server (REV2) change to the wp_root/bin directory. This is the directory that contains WebSphere Portal tools.

    2. Export the staging server (REV2) configuration using the XML configuration interface and the provided sample file named Export.xml: 
      ./xmlaccess.sh -in Export.xml \
               -user wpsadmin \
               -password wpsadminpwd \
               -url http://stagingserver.setgetweb.com/wps/config \
               -out stagingserverREV2_config.xml

      The exported configuration is stored in the XML file named stagingserverREV2_config.xml.

  6. If you have installed other portlets or applications additional to the ones shipped with the portal, make sure to copy the necessary WAR files from the staging server to the installation directory wp_root/installableApps on the production server.

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

  7. Analyze the REV1/REV2 staging server differences

    1. On the staging server, stop the the portal server. Enter stopServer WebSphere_Portal -user admin_userid -password admin_password

    2. On the server where you just stopped the portal server, change to the wp_root/bin directory.

    3. To generate the differences file containing the additions and deletions configuration file, enter... 

      releasebuilder.sh -inOld stagingserverREV1_config.xml \
                  -inNew stagingserverREV2_config.xml \
                  outputfile.xml

      The resulting output configuration file will contain the additions and deletions to be imported onto your production server.

  8. The outputfile.xml which contains the differences between REV1 and REV2 portal server is then used to import these differences onto the production server

    Before importing, you might want to set the attribute...

    transaction-level="request"

    ...within the <request element.

 

Solutions to common WebSphere Portal XML Configuration Interface (XMLAccess) issues Technote (FAQ)

XMLAccess overwrites objects (sometimes referred to as 'artifacts' or 'resources') it finds on the target system with the values specified in the XML file. Objects not present in the target system but defined in the XML will be created. Additional objects on the target system will be ignored; these objects should be removed prior to import, either manually using the user interface (UI) or using XMLAccess.

  1. XMLAccess cannot be used to transfer credential vault data between Portal servers. If you do so, an export file that contains credential data for credential segments that exist on the receiving Portal server generates the following warning during import: 

    <status element="credential-segment _E_0O0KBAKJRF0IH2NR_36 name=DefaultAdminSegment" 
        result="warning"> 

    <message id="EJPXA0090W">
           com.ibm.wps.command.xml.XmlCommandException: EJPXA0090W: 
           It is not possible to modify credential-segment resources. 
           Existing settings are left unchanged. credential-segment _E_0O0KBAKJRF0IH2NR_36 
           name=DefaultAdminSegment
    <message>

</status>

  2. XMLAccess does not support SSL. Support is planned for a later release. As a workaround, use the internal transport port (9081 by default).

 

Deploying portlets in a cluster

Deploying portlets in a Portal cluster is a three-step process, even if active="true" is set in the XML file for all deployed portlet applications when the portlet applications are deployed. The steps are as follows:

  1. Deploy the portlet applications to one node

  2. Synchronize the nodes

  3. Activate the installed portlets using the Portal user interface, XMLAccess, or, in Portal Server 5.1.x, use the wpsconfig task "activate-portlets" (however, the task cannot be used to selectively activate portlet)

A sample Portal version 5.0.x XML file to activate the deployed portlets is shown below. Repeat the same XML for each deployed portlet. Note: Portal 5.1.x uses the schema PortalConfig_1.3.xsd. 

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

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

        <portal action="locate"> 

            <web-app action="locate" 
                     uid="com.ibm.wps.portlets.welcome"> 
    
                <portlet-app action="update" 
                             active="true" 
                             uid="com.ibm.wps.portlets.welcome.1"/>

        </web-app>
    </portal>
</request>

 

Handling deleted objects

When moving from one system to another, for example from staging to production, page deletions made on the staging portal are not transferred using XMLAccess. The generated XML file contains only what is currently defined in the staging system, and there is no way to record what was deleted. During import, only existing resources are updated or new resources are created. Existing objects in the production system that are not referenced in the XML file will not be deleted.

 

Differential updates

In Portal server 5.0.x, it is not possible to do differential updates, only full exports/imports (unless you want to track changes manually and individually, which is a very time-consuming and error prone process and is to be avoided).

Portal server 5.1.0 includes the ReleaseBuilder tool that creates a "diff" (a new XML file) between two exports and the diff can then be imported to the target system.

 

See also

 

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

 

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