Breakdown of WebSphere portal Solution Release Elements

The following section provides an overview of the components and entities which make up a complete Solution Release. This section provides a listing of the components and entities, while a subsequent section provides greater detail on the consideration for moving the components between environments.

 

Portal Artifacts

Portal Artifacts are stored in the portal file system. All deliverables of software development are usually artifacts (otherwise referred to as software components).

The following components are portal artifacts:

• Portal System Configuration (property files)
• Themes and Skins (JSP files and stylesheets)
• Portal Customizations (Java Classes)
• Portlet services, Active Credentials, Credential VaultAdaptors
• Portlet Code (Java Classes, JSPs, XML files)
• Portal Filters (Java Classes)
• Servlet Filters (Java Classes)
• J2EE Artifacts (managed by WebSphere Application Server)

Portal Extension Artifacts

Portal Extension Artifacts are stored in the portal file system or in a database. These artifacts exist in an installed portal system. They belong to components that are installed together with the portal but are not core portal components. Typically these components are available with and without the portal server.

The following components are examples of portal extension artifacts:

• Portal Search and search collections.
• Web Content Management
• Document Repository
• Documents, flows, roles
• Collaboration Components

Portal Configuration

The Portal Configuration is stored in the portal configuration database. It consists of configuration entities. Each portal resource is represented by one portal configuration entity in the portal database.

The following entities are part of the portal configuration:

• Portal Content Tree (Navigation, Pages, Layouts)
• URL Mappings
• Portlet Application Configurations
• Portlet Application Settings
• Portlet Configurations
• Portlet Settings
• Portlet Data (legacy portlets)
• Portlet Preferences (JSR168 portlets)
• Access Control Data (Roles, ActionSets)
• Credential Data
• Themes
• Skins
• Cross-page wires

Although Portal 6.1 provides valuable tools to aid in the movement of the Solution Release to the next environment in your release cycle, there are some components of the Solution Release that require extra steps. This section provides an overview of which tools are optimal for each of the components, and discusses the components that you will need to perform additional steps for.

The figure below (2.4-1) is provided as a visual breakdown of the solution release components and to help understand the form for the different components, how they are stored, and ultimately how they need to be managed when moving components of a solution release from one environment to another.

 

 

Portal Artifacts – the components involved and considerations for moving them

The first group of components are the parts of the Portal site that reside in the portal file system. Along with property files, the deliverables from your software developers that can include JAVA classes, war files, or other J2EE resource artifacts such as EJBs are also included in this category. The group is comprised of several different asset types, but because they are not stored within the Portal database, XMLAccess, ReleaseBuilder and the Site Management tools are not able to transfer them over to the new Portal system. The following sections provide an overview of some asset types included in this category.

Property files

In general, changes made to Portal property files on the source system need to be reviewed to determine if it is also appropriate for them to be made on the target system.

Because property files are used for many different purposes, there is not a single rule that is applicable in all cases. Portal property files can be modified via several different methods, including via manual update, via ConfigEngine helper files, or the WebSphere Administrative Console. If it is appropriate to make the changes to the target system, then the corresponding changes should be made on the target system via the same mechanism the change was made on the source system. It is not recommended to copy property files from one system to another.

Manual changes made to property files on one portal system will also need to be manually made on the target portal environment. Careful consideration needs to be made to ensure the property files contain information that is accurate for the target system which may not be the same as the source system, when appropriate. Property files that are typically manually modified during Portal installation and customization are in the <wp_profile>/ConfigEngine/properties directory:

• wkplc.properties
• wkplc_dbtype.properties
• wkplc_comp.properties

For example, the dbURL entries in the wkplc_comp.properties file must point to the correct servername for the target system, if the database server being used on the target server is different from the source.

Other property files may be changed via the ConfigEngine utility and helper files.

An example of a property file that may be changed this way is the wkplc.properties file.

After you make changes to <wp_profile>/ConfigEngine/config/helpers/ wp_security_ids.properties to match your LDAP configuration, execution of the ConfigEngine with the -DparentProperties -DsaveParentProperties=true flags, ConfigEngine will automatically save the properties from the helper file into the wkplc.properties file. As was the case with property files that were changed manually, the same steps that were taken on the source environment need to be taken on the target environment to propagate the changes there when required.

Portal configuration service property files are modified via the WebSphere Administration Console. Customizations made to these types of property files are stored within the portal profile root and also under the PortalServer base directory. Some service configuration properties can be set by modifying the propery files and then enabling them through a Portal configuration task, but this method is not available for all configuration tasks. It is important to note that if you want to move portal configuration service property changes from one portal to another, it is recommended to make the changes to the target environment in the same manner that they were made on the source environment.

On production systems, it is recommended to use the PropFilePasswordEncoder script in the (wp_profile_root)/bin directory to encode any passwords contained in External Security Manager property files.

Themes and Skins

The JSP files and stylesheets that make up the Themes and Skins are stored in the Portal file system. Although the portal pages that refer to or use the themes and skins can be moved to a new portal system via the XMLAccess or Site Management tools, the actual files that make up the Themes and Skins need to be manually transferred to the new system. The XMLAccess tools can also be used to move Theme styles and Theme polices to the new system. Section 4.4a (Deploying Themes and Skins) provides the steps to deploy a new theme and skin and also contains details about moving them to another system.

Portlet Code (Java Classes, JSPs, XML files)

Portlet applications are made up of Java Classes, JSPs and XML files packaged inside of a Portlet war file. During portlet war file installation, the WebSphere Application Server unpacks the WAR file and places the portlet classes and resources in the file system. The following example shows where the portlet files are placed on the filesystem and which files need need to be manually transferred to the new system during a move.

 

Specific Example – Portlet deployment and move – Effect on component files

To show where portlet classes, JSPs and XML files are placed on the filesystem when a portlet war file is deployed with the Portal Administration Portlets, we downloaded the IBM Portlet for Google Gadgets from the Portlet Catalog:

The IBM Portlet for Google Gadgets is a JSR 168 portlet that has these characteristics when deployed:

1. It's enterprise application (ear) file name is PA_IratedGoogleGadges.ear
2. It's portlet application name is com.ibm.wps.portlets.gadget.integrated.9730c9c350.webmod
3. The portlet's title is IBM Portlet for Google Gadgets

 

Before deploying the portlet, we confirmed that it was not already installed by looking in the following places on our wps01 development Portal server:

1. The WebSphere Administrative Console, list of installed Enterprise Applications:



2. The filesystem, there is no expanded PA_IratedGoogleGadget.ear in these folders:

•  C:/ibm/WebSphere/wp_profile/config/cells/node01/applications/



•  C:/ibm/WebSphere/wp_profile/installedApps/node01/



•  In the filesystem, there is no folder with the portlet application name in

C:/ibm/WebSphere/wp_profile/PortalServer/deployed/archive

3. Lastly, we confirmed that the GoogleGadget web module is not present with the Portal Admistrative Portlets > Portal Management > Web Modules, search:

 

We deployed the GoogleGadget portlet web module with the Portal Administrative Portlet: Administration > portlet management > web modules > click Install :

 

 

After successfully completing the installation, we confirmed that the installation resulted in changes to the above referenced locations:

 

1. The WebSphere Administrative Console, list of installed Enterprise Applications:



2. In the filesystem, the expanded PA_IratedGoogleGadget.ear was in these folders:

 

•  C:/ibm/WebSphere/wp_profile/config/cells/node01/applications/



•  C:/ibm/WebSphere/wp_profile/installedApps/node01/



•  In the filesystem, there is a folder with the portlet application name in

C:/ibm/WebSphere/wp_profile/PortalServer/deployed/archive



 

3. Lastly, we confirmed that the GoogleGadget web module was present with the Portal Admistrative Portlets > Portal Management > Web Modules:

The Google Gadget portlet shows up in the portlet search:

 

Moving Portlets

Prior to moving the portlet over to our wps02 staging server from wps01, we confirmed that it was not already installed on wps02 by looking in wps02's WebSphere Administrative Console, that it's ear was not expanded on the fileysystem, and by searching for it with the Portal Administrative > Manage Web Modules Portlet:

Moving the Portlet resources to another machine as part of a Portal release move, involves two steps:

1. Copy the portlet application's folder com.ibm.wps.portlets.gadget.integrated.9730c9c350.webmod and it's contents
   • from the source machine:
   • to the corresponding folder on the target machine. You can use FTP or any other method to move the files over. In our case, we mapped the wps02 c: drive as a local drive:

C:/ibm/WebSphere/wp_profile/PortalServer/deployed/archive

Y:/WebSphere/wp_profile/PortalServer/deployed/archive

 

This shows the contents of wps02 after the folder is copied over:



Note that this folder contains the portlet war file:



 

2. Use release builder and xmlaccess to deploy the portlet and move it's configuration information over to the wps02. The instructions to do this are described in section 4.3b Specific Example - Portal Transfer with Release Builder.

 

The differences file that was used in this case contained information about the newly installed portlet:

<web-app action="update" active="true" domain="rel" objectid="1_CGAH47L000DHD02ND921NR2002" removable="true" uid=" com.ibm.wps.portlets.gadget.integrated.9730c9c350.webmod "> 
<url>file://localhost/$user_install_root$/PortalServer/deployed/archive/com.ibm.wps.portlets.gadget.integrated.9730c9c350.webmod/GoogleGadgetIntegrated.war</url> 
<context-root>/wps/PA_IratedGoogleGadget</context-root> 
<display-name>PA_IratedGoogleGadget</display-name> 
<access-control externalized="false"owner="uid=wasadmin,o=defaultwimfilebasedrealm" private="false"/> 
<servlet action="update" active="true" domain="rel" name=" GoogleGadgetsIntegrated " objectid="V_CGAH47L000DHD02ND921NR2001" remote-cache-dynamic="false"/> 
<portlet-app action="update" active="true" defaultlocale="en" domain="rel" name=" com.ibm.wps.portlets.gadget.integrated.9730c9c350 " objectid="2_CGAH47L000DHD02ND921NR2006" uid="com.ibm.wps.portlets.gadget.integrated.9730c9c350"> 
<access-control externalized="false" owner="uid=wasadmin,o=defaultwimfilebasedrealm" private="false"/> 
<portlet action="update" active="true" defaultlocale="en" domain="rel" name="GoogleGadgetsIntegrated" objectid="3_CGAH47L000DHD02ND921NR2005" provided="false" servletref="V_CGAH47L000DHD02ND921NR2001"> 
<access-control externalized="false" owner="uid=wasadmin, o=defaultwimfilebasedrealm" private="false"/> 
</portlet> 
</portlet-app> 
</web-app> 

The xmlaccess command we used in this case to import the configuration containing the portlet was as follows:

• xmlaccess.bat -in Nov25.differences.xml -user wpsadmin -pwd wpsadmin -url http://wps02.itso.ibm.com:10040/wps/config
  1. The WebSphere Administrative Console, list of installed Enterprise Applications now shows the newly installed PA_IratedGoogleGadget ear:

   

  2. In the filesystem, the expanded PA_IratedGoogleGadget.ear was placed in these folders during the deployment:

     •  C:/WebSphere/wp_profile/config/cells/wps02Cell01/applications/

     

     •  C:/WebSphere/wp_profile/installedApps/wps02Cell01/

     

     •  In the filesystem, there is a folder with the portlet application name in C:/ibm/WebSphere/wp_profile/PortalServer/deployed/archive because we moved it there manually as described above.

  3. We confirmed that the GoogleGadget web module was present with the Portal Admistrative Portlets > Portal Management > Web Modules:

  

  The Google Gadget portlet shows up in the portlet search:

  

  4. Lastly, we confirmed that the WebSphere Application Server configuration on the wps02 target machine was updated with information that the newly installed application was deployed to our WebSphere_Portal application server, as shown in the following extract from the serverindex.xml file: C::/WebSphere/wp_profile/config/cells/wps02Cell01/nodes/wps02/serverindex.xml:

The successful output of this command can be seen in the following screen capture:



After successfully completing the portlet move with xmlaccess, we confirmed that the move resulted in a deployment by seeing changes to these locations:

 <serverEntries xmi:id="ServerEntry_1213915749762" serverName="WebSphere_Portal" serverType="APPLICATION_SERVER"> 
... 
<deployedApplications>PA_IratedGoogleGadget.ear/deployments/PA_IratedGoogleGadget</deployedApplications>

 

Once these two steps are complete, the portlet was available for use on wps02. Because our wps02 environment contains a portal cluster, synchronization was needed before the portlet could be used. This step would not be necessary in a standalone portal environment.

Other Portal Customizations and considerations for Portal Artifacts

If your customized portal site makes use of other Java Classes that are not included in any of the above referenced locations, then they will also need to be moved manually. An example of this type of file may be shared libraries that contain resources used by or shared across several components or portlets within the portal. A common practice is to place shared library jar files in the /PortalServer/shared/app directory because this directory is already configured to be in the classpath for the predefined WPSLib shared library for WebSphere Portal. The following image shows the list of predefined shared libraries including WPSLib that can be seen from the WebSphere Administrative Console:

The following figure shows WPS_HOME/shared/app and elements of the classpath for the predefined WPSLib shared library:

If the shared library that is being moved to the new server is located in a directory that is not preconfigured to be a part of a configured shared library classpath, then a new shared library was created and the new directory added to it's classpath in the WebSphere configuration to allow the library to be loaded on the source server. Adding the shared library and it's classpath entry will also need to be done on the target server and either via the WebSphere Administrative Console or with a wsadmin command similar to the following:

$AdminConfig create Library $server {{name myLibrary} {classPath 
c:/WebSphere/PortalServer/shared/app/myLibraryClasspath}} 

 

Portal Filters

A portlet filter is used to intercept and modify the output of a portlet before it is aggregated to the entire portal page. Filters can be used to produce output in different markups, languages or formats than what was originally intended by the portlet. The Java classes that make up the filter itself are stored within portlet war files and so the same instructions apply to moving filter Java Classes as for Portlet war files.

Using portal filters requires that the Portlet Container Service properties be modified to enable portlet filtering for the site and each filter must be registered to the PortletFilterService. In the filesystem, these changes are made to configuration files via the WebSphere Administration Console. If you make changes on your source server to the Portlet Container Service or PortletFilterService that result in updated Portal properties files, then you will need to also make the same changes on the target server as part of the move.

Lastly, the filter needs to be applied to the Portlet via the Manage Portlets portlet. Changes made to which portlet the filter is applied to via the Manage Pages portlet, can be moved to the new system with the Portal transfer tools.

Portlet services, Active Credentials, Credential VaultAdaptors

If our solution release contains custom written portlet services to be used in place of the provided credential vault portlet service or custom vault adapters, then they may be packaged as separate shared libraries. Corresponding custom portlets can be written to extract user's credentials from the vault for use in accessing remote applications. If this is the case, then the same steps that are required to move shared libraries between portal systems.

Vault segment information and is stored in the portal release database therefore can be moved with releasebuilder and xmlaccess tools as part of a solution release move. Public credential vault slot data should be picked up by xmlaccess and releasebuilder tools. These resources appear as "<credential-segment" and "<credential-slot" in the xmlaccess export file. Private slots (for example those created by a portlet for a specific user) should be going into the customization domain and will not be transferred with the releasebuilder/xmlaccess interface tools as part of a solution release move.

J2EE Artifacts

J2EE resources or artifacts (such as EJB jar files) used by Portlets are typically packaged in the same EAR with the portlet application war and can be deployed using the WebSphere Application Server Administration console, instead of using the portal Manage Web Modules administration portlet or the XML configuration interface.

After the EAR is deployed via the WebSphere Application Server (either the scripting interface or administrative console), the XMLAccess configuration interface must used to deploy and register the portlet application(s) packaged within the ear to the Portal server, which makes it available for use within Portal. The WebSphere Portal 6.1 InfoCenter contains the instructions for doing this with the RegisterPreDeployedEAR.xml in the article:

Deploying J2EE resources

http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/topic/com.ibm.wp.ent.doc/admin/j2ee.html

Once the portlets are registered with the portal server, the Portal Administration portlets can be used to configure and remove them, but this removing the portlets via the Portal administrative portlets does not remove the EAR that they are part of from the WebSphere Application Server. To completely remove the EAR, it must be deinstalled via the WebSphere Application Server.

When updating a predeployed enterprise application that contains one or more portlets, the update must be made in the WebSphere Application Server. The steps to update the ear are beyond the scope of this topic, and are documented in the WebSphere Application Server InfoCenter. If the change to the ear includes modifications to the web.xml or portal.xml of an encapsulated portlet, then the Portal server must be made aware of the updates by using the XMLaccess configuration interface. The same RegisterPreDeployedEAR.xml sample file can be used, but please ensure the <web-app> tag has an attribute action="update" and not action="create" for it to work a second time on a predeployed ear.

When moving a solution release that contains portlets deployed in an EAR, deploy the EAR within WebSphere Application Server and in Portal via XMLAccess / RegisterPreDeployedEAR.xml on the target machine, prior to moving the remainder of the solution release elements. Note that the export XML file from the target server will show that the portlet is part of a webapp that is predeployed with this flag:

<web-app action="update"... 
predeployed="true"  removable=…>

The same is true for moving an updated EAR to a portal server as part of a solution release move. Update the ear via the WebSphere Application Server on the target machine and then use the XMLaccess configuration interface to notify the Portal server of the updates if the update includes changes to the portlet's web.xml or portal.xml files.

 

Portal Extension Artifacts – the components involved and considerations for moving them

Portal Extension Artifacts are stored in the portal file system or in a database. These artifacts exist in an installed portal system. They belong to components that are installed together with the portal but are not core portal components. Typically these components are available with and without the portal server.

Portal Search and search collections

It is possible to export Portal search collections in XML format through the Portal administration console.  Instructions for performing the export and import of search collections can be found at the link below: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/admin/srtexpimp.html

Web Content Management

Moving Web Content Management artifacts is handled via the Synchronization process. This topic is covered in detail in  Section V of this document.

Document Repository 

Starting in Portal 6.1 the Portal Document Manager tool is no longer available. The tool has been replaced by Lotus Quickr.  Below is a link to  Portal   Information   Center that provides information on migrating documents between Portal Document Manager and Lotus Quickr.

http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/migrate/mig_pdm2quickr.html

Collaboration Components

Collaboration components include a wide variety of Portal components including Domino and Extended Products such as Domino Web Access, Sametime Contact List, Lotus Notes View. It can also include various IBM products such as IBM Lotus SameTime and IBM Lotus Domino. More information on the Collaboration Components can be found at this Information Center link:

http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/collab/i_coll_c_collaboration.html

 

Portal Configuration – the entities involved and considerations for moving them

Portal Configuration information is the data representation of several kinds of portal resources that are stored in the portal configuration database. The portal configuration database is comprised of several different database domains, each of which holds a different type or category of data. Domains can be configured separately and split across different database management systems. Data is placed in each domain according to these criteria:

• Portal release data is made up of portal content definitions, rules, and rights. It is typically not changed once in production, but designed on a staging server and then moved over to production as part of a release with the releasebuilder/xmlaccess/site Management portlet tools. One copy of the release data exists per cluster. This is where content definition for these are stored:

•  
  • Portal Content Tree (Navigation, Pages, Layouts)
  • URL Mappings
  • Portlet Application Configurations
  • Portlet Application Settings
  • Portlet Configurations
  • Portlet Settings
  • Portlet Data (legacy portlets)
  • Portlet Preferences (JSR168 portlets)
  • Access Control Data (Roles, ActionSets)
  • Credential Data
  • Themes
  • Skins
  • Cross-page wires

The following two domains are typically shared across production servers, but not moved from staging to production during a solution release move:

• Customization data, includes data created by a portlet for a specific user,
• Community data represents resources modified during production, such as shared documents or application resources.

The remaining three domains represent non shareable data that have alternate means of moving if required:

• The JCR domain is where WCM documents are stored. (See Chapter 5 Synchronization for more information about this.)
• The Feedback domain contains site visitor usage pattern information, used for analytics.
• The LikeMinds domain contains user rating and action transactional information and rules used by the LikeMinds engines for the Personalization dynamic recommendation system.

There is further information about “Shared database domains”, in this Portal InfoCenter article:

http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/topic/com.ibm.wp.ent.doc/config/db_plan_domains.html

 

References used within Topic 2:

•  WebSphere Portal 6.1 InfoCenter: Manual steps prior to using ReleaseBuilder

http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/topic/com.ibm.wp.ent.doc/admin/dep_checklist.html

•  Hot deployment and dynamic reloading

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.base.doc/info/aes/ae/trun_app_hotupgrade.html

•  IBM Rational Application Developer V6 Portlet Application Development and Portal Tools

http://www.redbooks.ibm.com/redbooks/pdfs/sg246681.pdf

•  WebSphere Portal V6.1 Knowledge Transfer Presentations, A01v2, A08