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:

It's enterprise application (ear) file name is PA_IratedGoogleGadges.ear

It's portlet application name is
com.ibm.wps.portlets.gadget.integrated.9730c9c350.webmod

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:

The WebSphere Administrative Console, list of installed Enterprise
Applications:



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

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:

The WebSphere Administrative Console, list of installed Enterprise
Applications:



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



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:

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:



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
The WebSphere Administrative Console, list of installed Enterprise
Applications now shows the newly installed PA_IratedGoogleGadget ear:

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.

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:



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/a
dmin/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.w p.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.w p.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.w p.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/c onfig/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/a dmin/dep_checklist.html

• Hot deployment and dynamic reloading
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.ba se.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