+

Search Tips   |   Advanced Search

Portal stage process

  1. Overview
  2. Set up the initial stage and prod servers
  3. ReleaseBuilder
  4. Make updates using ReleaseBuilder
  5. Updates with syndication
  6. Staging Personalization rules to prod
  7. Staging and external security managers
  8. Staging from system without ESM to a system with ESM
  9. Staging from system with ESM to system without ESM
  10. ReleaseBuilder - End-to-End
  11. Artifacts


Overview

Staging components...

Portal artifacts include...

Environments...

The initial solution release (Full-Release 1.0) goes to an empty stage target and includes...

A differential release holds only the changes and not the complete release and is created by comparing two release exports from the same environment. ReleaseBuilder is the tool that helps with this task.

A virtual portal shares several resources with the main portal installation, especially all code artifacts and the JVM. When deploying a portal solution release to a virtual portal, these types of artifacts must not be deployed again. Redeploying can break references in other virtual portals. Shared resources must only be deployed to the master portal. To strip off the shared resources from an XML file, use the Release Builder tool in the virtual portal mode.

We can use portal application archive (PAA) for stage initial releases. Artifacts can be exported, moved to the target, and deployed using the Solution Installer. The PAA file can be augmented with custom actions to modify the behavior of the Solution Installer.

Syndication is another way to stage changes from the authoring system to the prod system, synchronizing content structure, navigation, and web content documents. Unlike the PAA process where the release data can be placed in media that can be copied between the systems, syndication uses http to move changes from one system to another, requiring a network connection. Because syndicated pages refer to portlets using the ID of the portlets, an initial stage needs to take place before syndication can be used.

For stage of WCM data, in addition to syndication, we can run export-wcm-data and import-wcm-data. Place the files in...

Each subdirectory represents a separate web content library. These libraries are a specialized form of JCR artifact. Web content libraries are separated into their own directory due to the process required to install them using the default functionality.

Options for copying static resources include...

For stage personalization rules and campaigns, use the pznload task. Place files in content/pzn. Personalization related artifacts, such as JAR files containing business rules and personalization .nodes files reside in this directory.

To stage portlet WAR files choose one or more of the following options...

More info...

For globally available shared libraries files, place JAR files into either...

These files are not copied to the equivalent directories.

For EAR files place files in...

Contains...

Components not handled by the initial import...


Set up the initial stage and prod servers

  1. Configure portal on the stage server, including database and security.

  2. Configure portal on the prod server, including database and security.

  3. Develop a release on the stage server.

    Pages, portlets, themes, skins, personalization rules, web content, and other items.

  4. Export the baseline release from the stage server:

    1. Export portal content... 

        cd WP_PROFILE/PortalServer/bin
./xmlaccess.sh -in $PORTAL_HOME/doc/xml-samples/ExportRelease.xml  \
               -out /rel/stagev1.xml  \
               -url "http://stage.myco.com:port/wps/config"  \
               -password password  \
               -user user_ID  \
               -password password

    2. Export Personalization rules... 

        cd /opt/IBM/WebSphere/PortalServer/pzn/prereq.pzn/publish  
. /opt/IBM/WebSphere/wp_profile/bin/setupCmdLine.sh  
./pznload.sh -serverurl "http://stage.myco.com:port/wps/pznpublish/pznpublishtarget"  \
             -targetpath /  \
             -username user_ID  \
             -password password  \
             -export  \
             -out /rel/pzn/rules.nodes

    3. Export WCM libraries... 

        ./ConfigEngine.sh export-wcm-data \
                  -DWasPassword=foo \
                  -DPortalAdminPwd=foo \
                  -Dexport.allLibraries=true  \
                  -Dexport.singledirectory=true  \
                  -Dexport.directory=/rel/content/wcm

      If the WCM libraries are in a virtual portal, add one of the following parameters...

        -DVirtualPortalHostName=myvp.myco.com Host name of the virtual portal.
        -DVirtualPortalContext=VirtualPortal1 Context root of the virtual portal.

    4. Export the custom themes and skins.

  5. On the prod server, go to...

      Administration > Web Content Libraries

    Edit any libraries that have the option...

      Prohibit library from being deleted

    ...and unselect that option.

  6. For each library on the system, select...

      Delete library

  7. Empty portal content from the prod server:

      ./ConfigEngine.sh empty-portal -DWasPassword=foo -DPortalAdminPwd=foo

    If you try to access the WebSphere_Portal server after running the empty-portal task, an error displays on the browser indicating that no content is available. We can ignore this message. It displays until you import another configuration onto the server.

  8. On the stage server...

      cd $WP_PROFILE/PortalServer/deployed
      tar cvf archive.tar archive
      tar cvf rel.tar /rel

    Extract the archive to the same location on the prod server.

  9. If the environments are not using the same LDAP, and distinguished names are different, this could cause problems.

    If the XML file contains only the administrator user or group, it probably will not be a problem, because the owner access will be changed to "unknown" and the current administrator will, in effect, be the owner anyway. However, if there are users or groups that are given certain access to artifacts like pages and portlets, and those group names are different in different environments, execute a global replace in the XML file the import into the new environment. For example, change "ou=dev,o=mycompany" to "ou=prod,o=mycompany".

  10. Import into the prod server:

    1. Import content 

      cd WP_PROFILE/PortalServer/bin
./xmlaccess.sh -in /rel/content/xmlaccess/install/stagev1.xml  \
               -url "http://stage.myco.com:port/wps/config"  \
               -user user_ID  \
               -password password

    2. Import Personalization rules. 

      cd /opt/IBM/WebSphere/PortalServer/pzn/prereq.pzn/publish  
. $WP_PROFILE/bin/setupCmdLine.sh  
./pznload.sh --serverurl "http://stage.myco.com:port/wps/pznpublish/pznpublishtarget"  \
             --targetpath /  \
             --username user_ID  \
             --password password /rel/content/pzn/rules.nodes

    3. Import WCM libraries: 

      ./ConfigEngine.sh import-wcm-data \
                  -DWasPassword=foo\
                  -DPortalAdminPwd=foo\
                  -Dimport.directory=/rel/content/wcm

      If the WCM libraries are in a virtual portal, add one of the following parameters...

      -DVirtualPortalHostName=myvp.myco.com Host name of the virtual portal
      -DVirtualPortalContext=VirtualPortal1 Context root of the virtual portal

  11. If importing to a cluster, to activate portlets, synchronize and restart all cluster members.

  12. Export or manually recreate any items that cannot be packaged.

  13. Make a backup of the system


ReleaseBuilder

ReleaseBuilder.sh compares a portal environment at one point in time, with the same portal environment at a later point in time. (R1 vs. R2), generating an XML file containing the differences. This file is imported into a different portal environment. Features in the target environment that are unchanged from R1 to R2 are not affected by the import. R1 and R2 are generated using xmlaccess.sh.

The diff file can be used to apply not only addition and update modifications but also deletions to the target server. This allows two portal servers, for example, a stage server and a prod server, to remain in synch.

ReleaseBuilder supports a virtual portal mode that allows the generation of difference configurations for virtual portal scoped resources only.

Unlike xmlaccess.sh, ReleaseBuilder does not interact with the portal server runtime.

xmlaccess.sh is used to export the before and after XML files. These two exports take place on the the SAME portal environment. ReleaseBuilder is not designed to determine the differences between or changes made to two separate Portal servers.

For the ReleaseBuilder tool to work, all Object IDs must be the same across all environments.

Best practice is to give all objects that you create a unique name, which helps humans pare the XML file, and helps the xmlaccess tool locate an object in the configuration, in case the internal Object ID has changed.


Make updates using ReleaseBuilder

  1. Create ReleaseBuilder checklist

  2. Export the stage server configuration R1 

    cd WP_PROFILE/PortalServer/bin
./xmlaccess.sh -in ExportRelease.xml \
               -user wpsadmin \
               -password wpsadmin_pwd \
               -url "http://stageserver.myco.com:port/wps/config" \
               -out stageR1_config.xml

    Export the entire portal configuration R1 of the stage server; do not include users, users' access control, or any other user configurations.

  3. Develop and test new functions and portlets on the stage server.

  4. Export the stage server configuration R2 

    cd WP_PROFILE/PortalServer/bin
./xmlaccess.sh -in ExportRelease.xml \
               -user wpsadmin  \
               -password wpsadmin_pwd  \
               -url "http://stageserver.myco.com:port/wps/config" \
               -out stageR2_config.xml

  5. If you have installed other portlets or applications additional to the ones shipped with the portal, copy the necessary WAR files from the stage server to the directory...

      WP_PROFILE/PortalServer/deployed/archive

    ...on the prod server.

    The deployed/archive directory is always located in the original WP_PROFILE installation path, even if the prod server is using an additional profile created after installation.

    On Windows, the name of the WAR file must be 25 characters or less.

  6. Optional: Stop the portal server on the stage system. This frees resources for computing the release difference.

  7. On stage server, generate the R1 vs. R2 differential file. 

      cd WP_PROFILE/PortalServer/bin
./releasebuilder.sh -inOld stageR1_config.xml  \
                    -inNew stageR2_config.xml  \
                    -out outputfile.xml

  8. If stopped, restart the portal server on the stage system.

  9. Import differences onto the prod server. 
      ./xmlaccess.sh -in outputfile.xml  \
               -user wpsadmin  \
               -password wpsadmin_pwd  \
               -url "http://prodhost.myco.com:port/wps/config"

If portlet parameters are deleted from a configuration, the output script generated by ReleaseBuilder does not remove those parameters on the target system.

XML files generated by ReleaseBuilder do not have any transaction levels set. To set a transaction level edit the XML file generated by ReleaseBuilder and add the transaction level to the XML file.


ReleaseBuilder command syntax

releasebuilder.sh generates different configurations for a single stage server. These configurations are promoted to higher life-cycle environments.

To execute...

...where...


Updates with syndication

After setting up the initial stage and prod servers and deploying the initial release, we can use the syndication feature of IBM Web Content Manager to update content in web content libraries. If managed pages are enabled, syndication also ensures that all required page artifacts are transferred along with the content.


Syndication and stage

We can use syndication to update content that was originally created by deploying portal solution releases with either...

We can also set up syndication between virtual portals or primary portals on the same system or between virtual portals on different systems.

Successful syndication requires that the object IDs for portlets, themes, and other artifacts are the same on both the syndicator and subscriber. Because the syndication process itself does not manage these artifacts, you must synchronize the two servers by an initial stage process before you syndicate. In addition, each time that you deploy an artiface that is not managed by syndication to the source portal, you must stage the artifact with the appropriate stage tool. However, if the source and target are different virtual portals on the same portal server, this step is unnecessary, because these artifacts are shared between virtual portals.

Syndication can be set up only between systems that use the same user repository.

Syndication for managed pages between multiple servers requires that you perform an initial stage to all the servers.

The syndication process performs a prerequisite check on the subscriber to ensure that any required themes, skins, portlets, or iWidgets on a page are present on the target system. If any required objects are missing on the subscriber, syndication is not performed for this page. This behavior can result in missing pages and syndication errors for affected pages. Use xmlaccess.sh to transfer the missing resources.

iWidgets and portlets can store data in the WebDAV file store. The syndication process does not verify or transfer WebDAV data. If a portlet on a managed page requires data from the WebDAV file store, manually copy the required objects to the target system.


Managed pages and syndication

If managed pages are enabled and we are using syndication as part of the stage process, the following considerations apply:

The ExportManagedPagesRelease.xml file is available for exporting all artifacts except pages and wires.

Related...


Staging artifacts not transferred by syndication

To export all portal artifacts except pages and wires,

We can use this file when stage to prod with managed pages. 

  
./xmlaccess.sh -in /opt/IBM/WebSphere/PortalServer/doc/xml-samples/ExportManagedPagesRelease.xml \
               -out /Sample1/content/xmlaccess/install/stage-version1.xml \
               -url "http://stageserver.myco.com:port/wps/config" \
               -user wpsadmin  \
               -password wpsadmin_pwd

The exported configuration is stored in stage-version1.xml.


Staging Personalization rules to prod

Method: Export from source then import into destination

Steps Advantages Disadvantages Users

  1. Use the Export button in the Personalization Navigator portlet on the source to export a nodes file.
  2. Use the Import button in the Personalization Navigator portlet on the target to import that file.
Easiest way to move rules. Cannot be scripted. Requires Personalization Navigator portlet to be installed on the target server. Development teams. Quick, ad-hoc changes in small deployments and test environments.


Method: Publish using the Personalization Navigator portlet

Steps Advantages Disadvantages Users
Use the Publish menu options in the Personalization Navigator portlet to publish the entire workspace or to selectively publish Once a publish server is configured, we can publish rules in two clicks. Does not require rules to be saved on the file system. publishing the entire workspace with smart delete, we can ensure two work spaces are the same. No intermediate file is produced by the process, so there is no record of what was published other than log files. This approach is driven from a GUI, so it is not scriptable. Business users with rule authoring responsibilities.


Method: Export from the source and then publish into the destination

Steps Advantages Disadvantages Users

  1. Use the export button in the Personalization Navigator portlet on the source to export a nodes file.
  2. Use the pznload command line utility (pznload.sh) to publish the nodes file that you exported to the target.
This method can an be scripted. Allows the changes to be tracked, controlled, and the earlier versions to be reverted by maintaining copying of the nodes files and rerunning a script. Requires use of a command line interface. Administrators


Staging and external security managers

Using an external security manager (ESM) for authentication has no impact on the stage to prod functionality. Using an ESM for authorizations does have an impact on the stage to prod scenario. The same ESM used for authorization must also be used to manage authentication.

Use the security manager to manage entities that the centralized security manager controls. Managing those entities elsewhere violates the principles of centralized security control. This principle does not change in stage-to-prod support. For stage-to-prod, this principle leads to the inability to modify security definitions of a resource that is externalized. The following sections describe the direct implications in ESM scenarios for stage-to-prod.

xmlaccess.sh is used for configuration management in the stage-to-prod support. xmlaccess.sh covers configurations managed by the portal. The XML configuration interface configuration files contain a list of all role mappings for all internally managed resources. Using ESMs allows management of entitlements for selected resources outside of the portal.

For IBM WebSphere Portal, xmlaccess.sh covers security definitions of externalized resources. This functionality for xmlaccess.sh allows us to provide a request parameter within an export request. This parameter causes xmlaccess.sh to include role mappings of all resources in the output file. The exported file contains role mappings for internally managed resources as well as externally managed resources. This allows for the stage of role mapping of all resources that are not already externalized in the target system.

The following support matrix illustrates stage support of entitlements in scenarion that involve ESM. The source system refers to the system from which the configuration is exported (typically the integration system). The target system is the system into which the configuration is going to be imported (for example, stage or prod system).

  no-ESM Target ESM Target
no-ESM Source All role mappings can be fully synchronized. Resources on the target system are initially managed internally after release stage.
Resources can be externalized on the target system. Role mappings of externally managed resources in the target system are reinternalized.
ESM Source Role mappings of internalized resources can be synchronized.

Synchronization of role mappings of externalized resources results in errors during import. (Manual configuration file updates ("change external to internal state") are required to prevent errors.)

Role mappings of internalized resources are fully synchronized.

Role mappings of externalized resources can be synchronized only on time of externalization.

Role mappings for resources that are externalized on the target system cannot be synchronized.

In summary, role mappings can be synchronized as long as the resource is managed internally by the WebSphere Portal server. Once the resource is externalized, role mappings are owned by the external security manager system and can not be synchronized. However, it is not possible to modify role mappings for existing externalized resources and synchronize their updated role mappings to a target system.


Staging from system without external security manager to a system with external security manager

This combination is used where the integration system is reduced as much as possible and is configured like a development environment rather than a prod environment.

All entitlements for all resources that are staged in this scenario are fully synchronized. All resources in the target system are managed internally. The external security manager is not used for managing authorization decisions.

It is possible to manually externalize resources. We can also manually edit XML configuration interface configuration files. In this step, all role mappings that were defined within the portal before are moved to the external security manager. Managing these resources externally might include updating the role mappings of these resources outside the portal.

During stage of subsequent releases, resources with updated entitlements will appear in xmlaccess.sh file as internally managed resources. These resources will be internalized at when this file is imported to the target system. Your can manually update the configurations for externally managed resources to prevent this. however, there is no build in support for managing these kinds of configurations. Special care must be taken to manually replicate all changes of role mappings of externalized resources on the target system.


Staging from system with external security manager to system without external security manager

It is unlikely that this scenario will be used by most customers.

In this scenario, entitlements for internalized resources can be staged without any limitations. These configurations appear as if the source system was not configured to use an external security manager.

If entitlements for resources that are externalized on the source system are staged, errors will occur on the target system. During import of this configuration, the target system will be asked to externalize a resource, but the system is not configured to support resource externalization. This results in an error condition.

These errors can be resolved by manually updating the configuration file to have all resources managed internally. If role mappings for externalized resources are contained in the configuration file, entitlements will be synchronized between the two systems.


ReleaseBuilder - End-to-End

For a tutorial that discusses deployments that leverage ReleaseBuilder, see: Managing the ReleaseBuilder deployment process for IBM WebSphere Portal


Artifacts

  1. WAS layer

    • Configuration settings
    • Enterprise Applications (EARs)
    • Web Modules (WARs)

  2. Portal layer

  3. WCM layer...

    • Design artifacts
    • Content artifacts

  4. PZN layer


See also

  1. Managing the ReleaseBuilder deployment process for IBM WebSphere Portal
  2. PZN prod stage
  3. Export and import web content libraries
  4. Transfer a complete configuration