Managing Portal 6.1 Environments

Fernanda Gomes

Carrie Hu

Corinne Letilley

Ivan Portilla

Matthew Stokes

Rahul Vyas

- 2 -

Introduction The following document (wiki) discusses best practices for building and managing your WebSphere Portal v. 6.1 Environment. High level information is provided about how to set up a Portal v. 6.1 Environment, including a development, staging and production environment. Within the context of each of these environments, we cover topics related to how to move changes through the system and successfully manage releases of a Portal 6.1 site.

Topics covered Topics which are covered include:

1. Overview of how to setup as Portal environment system a. High level discussion of the steps involved in setting up a Portal 6.1

Enviroment b. Introduction to the infrastructure used for the sample company River Bend

Tea and Coffee Co, illustrating a diagram of the environment and a discussion around why we made specific decisions to build the environment this way

2. Different kind of Portal content : pages, portlets, documents a. Conceptual overview of the different types of portal content and the

relationship between these elements b. Overview of the components and entities which make up a complete

Portal Solution Release c. Discussion how components and entities within a solution release are

moved between environments

3. Connecting Testing and Staging Systems / Recommendations on handling concurrent development

a. Discuss which test and staging systems are needed and how are they connected.

b. Introduce best practices and recommendations for organizing development teams and handling concurrent development efforts on the test and staging systems

c. Provide a specific case scenario example - illustrating how to use RAD v. 7.5 to move development artifacts from RAD v. 7.5 into a Portal 6.1 Environment

4. XMLaccess, Release Builder and Site Management - when to use what - how

to use the tools a. How to apply this to the flow of data through the

development/test/staging/prod phases, b. Describing each of the transfer tools – what they are and in which cases

they are appropriate to use,

- 3 -

c. Specific case examples - How to do the transfer using each of the specific tools

5. Syndication a. Provide a specific Syndication example as it applies to the River Bend Tea

and Coffee Company Portal v. 6.1 environment.

6. A fastpath for quickfixes a. This section provides an overview of the Portal product maintenance

strategy and how it applies to a Portal Infrastructure which includes several different Portal environments from development through to production.

b. This section also includes some consideration for the application of both emergency Portal product Interim Fixes and urgent customer application fixes.

7. Backup and Restore procedures

a. This section discusses best practices and specific methods to follow when performing back up and restore procedures.

- 4 -

Introduction to River Bend Tea and Coffee Company For the purpose of providing a realistic business context to this section, we use the River Bend Tea and Coffee Company as the basis for the development and portal 6.1 management scenario. River Bend Coffee and Tea Company, a subsidiary of WWCorp, is a fictitious company that uses Portal v. 6.1. It operates a chain of 20 retail stores in 12 cities worldwide. In addition, the company runs an Internet-based retail operation, offers small-scale catering services, and has launched a certification program for employees and customers who wish to become skilled roast masters. The figure below illustrates the customized home page produced for River Bend.

Throughout this wiki, we will frequently refer to River Bend Tea and Coffee Company for a realistic example of how to configure a three tiered environment, including a development environment, a staging environment and finally, a clustered production environment.

- 5 -

Topic 1. Overview of how to setup a Clustered Portal 6.1 Environment

Objective: The purpose of this section within the wiki is the following:

1. Establish a foundational understanding of the different tiers of the environment, namely the development environment, the staging environment and the production environment

2. Provide a high level overview of the key steps involved in setting up a Portal 6.1 Environment

3. Introduce the sample infrastructure used in the River Bend site. 4. Discuss the decisions in designing the sample infrastructure for the River Bend

Site.

Setting up a Portal 6.1 Environment This section of the document provides information and considerations when creating a Portal environment. There are several things to take into consideration when building environment, including the availability of system resources, external software integration, such as databases and LDAP external security and how the WebSphere Portal will be used. System resources is referring to hardware such as CPU speed, memory (RAM) and hard drive space. The availability of these types of resources will shape the formation of the environment since Portal has minimum system resource requirements. A link to the system resource requirements is provided below. External product integration refers to Portal resources such as databases, LDAP external security and web servers. This will have a major effect on how the environment is implemented, for instance in a non-development environment it is not supported to use the default derby database. The environment must be integrated with an enterprise level database such as DB2 or Oracle. Software requirements can be found at the link below. Both hardware and software requirements can be found at the link below: http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg27007791 The way the portal will be used will heavily influence the way the portal environment is created. One of the main considerations is the number of users that may be accessing Portal at any given time. As the number of users accessing Portal grows the strain on Portal resources will grow and as a result certain design considerations must implemented. These challenges can be met by increasing the environment hardware resources and creating cluster environments. The next few sections will go into specific considerations for Development, Staging and Production environments.

- 6 -

Development Environment A development environment is the environment on which pages, portlets and documents are initially created. In some cases there maybe numerous development environments in a given organization all involved in the development effort. Concurrent development methodologies are documented in “Section 3.2” of this document. One of the main considerations when building a development environment is how close should the development environment model staging and production environments. A development environment should definitely be at the same version level as the staging and production environment. If staging and production are clustered environments it is not usually necessary to also cluster the development environment. It is still possible move items developed on a stand alone development environment to a clustered staging and production environment. A major limitation to building a development environment as a cluster is that in most cases a development environment exists on a developer's personal machine which has a limited amount of hardware resources (CPU speed, RAM, etc.) available which restricts the ability to cluster. Another consideration is whether to migrate the development to an enterprise level database such as DB2 or Oracle. As a default Portal installs and is configured with Derby database. Derby has a smaller footprint and therefore is more reasonable an option on a developer's environment that may not have the resources to install an enterprise level database. Leaving the development environment configured to the Derby database will not cause issues later during data migration efforts to staging and development.

Staging Environment The staging environment serves as the model on which items produced on the development environment are tested. The staging environment may also be referred to as the quality assurance environment. A variety of aspects are tested on this environment including functionality, performance and appearance. The staging environment is not accessed by customers, but rather may only be accessed by internal developers or those assigned to test functionality. A staging environment should mirror the production environment as close as possible. Since the purpose of this environment is to serve as a testing ground for various portal elements it is important that the environment match as closely as possible to the production environment in case certain environmental factors come into play when portal elements are in use. If a production environment is clustered then it is necessary to also cluster the staging environment, however it is not necessary to have the same number of nodes. Also since a production environment must be integrated with a enterprise level database server, the staging environment must also be integrated with an enterprise level database server. Again it is important that the exact same database product and version be integrated on both staging and production environment.

- 7 -

Production Environment The production environment is the user facing environment that external customers or internal employees will access. At this point testing is complete and final version of portlets, pages and documents are released for use. Production environments must use an enterprise level database such as DB2 or Oracle. It is not supported to stay integrated with default Derby database. A major consideration to make when building a production environment is how many people may be accessing the environment at any given moment. If there are a large number of users accessing Portal than steps need to be taken mitigate the effects of having this many users trying to access Portal. This is accomplished by building a cluster environment. A cluster will allow multiple Portal instances, called Nodes, to be managed centrally by a Deployment Manager (DMGR). As the number of potential users increases the number of nodes must be increased to account for these users and assure constant availability to users. The DMGR will work to manage the number of users that access each portal effectively balancing user access so that one or more Portal instances is not overburdened.

Case Study Environment Creation Flow Chart In the following section, the intent is to provide a high level overview of the key steps involved in building a clustered Portal 6.1 Environment. For specific details beyond what is covered in this document, please reference the document, “A Step-By-Step Guide to Configuring a WebSphere Portal v6.1.0.0 Cluster using WebSphere Application Server v6.1.0.15”, which can be referenced at the following URL: http://www-01.ibm.com/support/docview.wss?rs=688&ca=gopack&uid=swg21313184 To build the environment used in this document, the Portal 6.1 Cluster Guide was referenced. A link to this guide is provided below. http://www-01.ibm.com/support/docview.wss?rs=688&ca=gopack&uid=swg21313184 In the section below, we provide a high level flow chart that diagrams the major steps to creating the environment.

- 8 -

- 9 -

Case Study – Building the Portal Environment for River Bend Tea and Coffee Company For the purposes of this document, we built a sample environment for a fictitious company, River Bend Tea and Coffee Company. In this example, three distinct environments have been created; a development, staging, and production environment. All three environments consist of both a WebSphere Portal (Portal) and Web Content Management (WCM). It is possible to install just Portal or WCM, however in this document we will seek to show movement of both Portal and WCM data through the environment.

• The development environment is a stand alone environment with DB2 as its back end database.

• The staging and production environments are both two node clusters which also use DB2 as their back end database.

Below is a conceptual diagram representing the total environment. Please note the fact that there is one single DB2 server. which contains three separate database instances that house the Portal database domains for each respective Portal/WCM environment.

- 10 -

Figure 1-1 - Conceptual digram of case study environment

Details on the Development Environment The development environment referenced in this document consists of a stand alone Portal/WCM server instance with DB2 as its back end database. This is starting point for data migration. DB2 was chosen as the back end database, as opposed to using the default Derby database, as there was an availability of system resources which allowed the development environment to use DB2 as its back end database. Below is a diagram outlining the development environment

- 11 -

Figure 1-2 - Diagram of Development environment

Below are the specific components and the corresponding version levels:

1. Standalone WebSphere Portal and Web Content Management 6.1.0.0 2. WebSphere Application Server 6.1.0.15 3. DB2 9.1.0.5 4. Processor: Intel P4 3.00 GHz Memory: 4 GB RAM

Details on the Staging Environment The staging environment will consist of a two node cluster with Portal and WCM. The Staging environment will also use DB2 as its back end database. The Staging environment will be an exact mirror image of the development environment. In this case the resources were available to create a Staging environment that mimics the Production environment exactly. In most cases this is most ideal since the goal of the Staging environment is to best match the Production environment. The rationale for this is because the staging environment serves as real world testing ground.

- 12 -

Below is a diagram outlining a staging environment:

Figure 1-3 - Diagram of Staging environment

Below are the specific components and the corresponding version levels:

1. Two node cluster with WebSphere Portal and Web Content Management 6.1.0.0 2. WebSphere Application Server 6.1.0.15 3. WebSphere Application Server Network Deployment 6.1.0.15 4. DB2 9.1.0.5 5. Processor: Intel P4 3.00 GHz Memory: 4 GB RAM

Details on the Production Environment The Production environment will also be a two node cluster with both Portal and WCM. The back end database for this environment is DB2. This is the final point in that data movement process. This represents the customer facing portion of the environment. Below is a diagram of the Production environment:

- 13 -

Figure 1-4 - Diagram of Production environment

Below are the specific components and the corresponding version levels:

1. Two node cluster with WebSphere Portal and Web Content Management 6.1.0.0 2. WebSphere Application Server 6.1.0.15 3. WebSphere Application Server Network Deployment 6.1.0.15 4. DB2 9.1.0.5 (need to determine exact DB2 product name) 5. Processor: Intel P4 3.00 GHz Memory: 4 GB RAM

- 14 -

Topic 2. Different kind of Portal content : pages, portlets, documents

Objective: The purpose of this section within the wiki is the following:

1) Establish the conceptual relationship between the WebSphere Portal product and the components which provide the content, namely the portlets and the pages which aggregate the portlets.

2) To help explain the different components or artifacts that make up a solution

release, which is defined as all portal resources with the exception of the WebSphere Portal product itself.

3) Considering what makes up a solution release, we apply this knowledge to

considerations for moving a solution release from a source environment to a target environment. This introduces the configuration management tasks, tools and utilities that are needed to move each of the component element types in a solution release.

2.1 Introduction to types of portal content When a user browses to a web site that is using WebSphere Portal software, they are accessing a single point of entry to many different Web-based resources. WebSphere Portal aggregates those resources in one place and requires the user to only log into the portal itself and not to each resource separately.

Understanding the hierarchical relationship between WebSphere Portal, portlets and pages. At a product level, the Portal web site has WebSphere Application Server software installed which provides the foundation for the WebSphere Portal Server. Many complementary products may also be used, and from the WebSphere Portal Server family comes the content offering (web content management and enhanced workflow capabilities) and the extend offering (powerful collaborative features). The WebSphere Portal product provides a framework for personalization and productivity functions as well as scalability. An important part of any Portal site, is the use of portlets. Portlets are pluggable Java servlets that are used to display web content, or provide access to applications and web services. Output from each portlet is a fragment of markup code that is displayed in its own portlet window. A portal page is an aggregation of portlet output windows. A rich

- 15 -

set of portlets are shipped with WebSphere Portal, including local and remote rendering portlets for displaying web content management data and many others. An API is also included in the product that can be used by developers to create custom portlets. Figure 2.1-1 below is intended to depict the relationship between the overall WebSphere Portal product, Portlets and the pages which present an aggregation of portlets.

Figure 2.1-1 – Conceptual relationship between portal, pages and portlets

Customization Customizations to the Portal site can be made to change its look and feel to match your organization’s standards. The content displayed on the Portal pages and can vary by users or groups in accordance with user profiles and business needs, and also by the type of device the web page is displayed on. Additionally, users have the ability to further customize their own view of the data, including which portlets are displayed, their arrangement on the page and the color schemes used by them. Figure 2.1-2 below illustrates our customized Portal page containing Portlets , and showing links to other Portal pages which make up the larger site.

- 16 -

Figure 2.1-2 – Example of portlets on a page within the customized RiverBend Site

Designing the high level site structure for River Bend The following diagrams represent the initial wireframe diagrams used to design the site and page layout. The core idea within the site was to 1) have a central welcome page, 2) a page dedicated to coffee, and 3) a page dedicated to tea. The key point here is that it is critical to plan the site layout and understand the placement and relationship between the portal pages and the placement of portlets. Using tools and techniques such as a basic wireframe diagram shown in the figure below is one approach to accomplish this.

- 17 -

W1- Pretty Picture[Side

Navigation]Teas

CoffeesW3-

WelcomeMessage

W2 -Login

welcome page Logo Search

W4 -Links

.

.

[Side Nav]Tea

HerbalBlack

T1 -Content

T2-Fun

Facts

LogoTea page(s) Search

T3 -Links

.

.

[Side Nav]Coffee

DecafColombian

C1 -Content

C2-Fun

Facts

LogoCoffee page(s)

Search

T3 -Links

.

.

Figure 2.1-3 – Wireframe Diagram used to plan site structure

2.2 Solution Release Terminology Once the Portal software is installed and the customization of the site has reached a stable state, a solution release can be created. A solution release is the site developed by you,

- 18 -

consisting of portal configuration + portal artifacts + extension artifacts, but not including the WebSphere Portal product itself.

Components of a Solution Release

Portal configuration - This is the configuration done by administrators and shared between multiple users. Configuration done by individual portal users is not included in the solution release. Portal configuration information is stored as configuration entities in the portal configuration database.

Portal artifacts - Software development deliverables are usually stored on the portal file system as artifacts.

Extension artifacts - Elements that belong to components that are not part of the core Portal, such as search collections, WCM, and collaboration components are extension artifacts. The Portal Extension Artifacts can be stored on the portal file system or in a database.

Types of solution Releases

Initial – the first solution release. The process of applying this initial solution release to an empty Portal is called staging of Portal Release version 1.

Differential – subsequent solution releases. Differential releases are used to

update an existing portal solution release to a new solution release (V1 to V2) by adding and deleting required resources.

Figure 2.2-1 below illustrates a schematic of many of the components which make up a solution release.

- 19 -

Figure 2.2-1 – components of a solution release Depending on the needs of your organization, your entire portal infrastructure might be contained on a single box, or distributed across multiple systems or even locations. In all but the most basic of Portal landscapes, solution releases must be moved between the different environments within your Portal landscape, from development to production. Because the elements that make up the solution release vary greatly from one another, the tools required to move or stage them between the different environments also vary greatly. Within this wiki, we focus on using the following methods and tools to move information between environments:

• XMLAccess • Release Builder • Site Management

This section provides an overview of the configuration management tasks, tools and utilities that are needed to move each of the component element types in a solution release from a source environment to a target environment.

2.3 Breakdown of 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

- 20 -

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)

- 21 -

• Portlet Preferences (JSR168 portlets) • Access Control Data (Roles, ActionSets) • Credential Data • Themes • Skins • Cross-page wires

2.4 Movement of Solution Release Elements 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.

- 22 -

Portal Solution Release

Portal Configuration Portal Artifacts Extension Artifacts+

Portal Configuration

DB

Including:Files,Classes,JSPs,

Managed using tools including - XML Access, - Release Builder, - Site Management

Including:Search Collections,Web Content ManagementDocuments, Roles, Collaboration Components

+

Including:Content Tree,Portlet SettingsPortlet ConfigAccess Control Themes, Skins

Managed within the Portal File System

Managed both from the File System and within a database

Comprised of …

Managed by…

Figure 2.4-1 – Components of a Solution Release and Methods for managing

2.4.1 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

- 23 -

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.

- 24 -

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:

- 25 -

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:

- 26 -

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\

- 27 -

• 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

- 28 -

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

- 29 -

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 o from the source machine:

C:\ibm\WebSphere\wp_profile\PortalServer\deployed\archive o 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: 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.

- 30 -

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

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 successful output of this command can be seen in the following screen capture:

<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>

- 31 -

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

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

shows the newly installed PA_IratedGoogleGadget ear:

- 32 -

2. In the filesystem, the expanded PA_IratedGoogleGadget.ear was placed 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:

- 33 -

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:

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 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:

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

- 34 -

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}}

- 35 -

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

- 36 -

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.

2.4.2 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.

- 37 -

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

2.4.3 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:

- 38 -

o Portal Content Tree (Navigation, Pages, Layouts) o URL Mappings o Portlet Application Configurations o Portlet Application Settings o Portlet Configurations o Portlet Settings o Portlet Data (legacy portlets) o Portlet Preferences (JSR168 portlets) o Access Control Data (Roles, ActionSets) o Credential Data o Themes o Skins o 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: 1. 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

- 39 -

2. 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

3. IBM Rational Application Developer V6 Portlet Application Development and Portal Tools

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

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

- 40 -

Topic 3. Connecting Testing and Staging Systems / Recommendations on handling concurrent development

Objective of this section The purpose of this section within the wiki is the following:

• Discuss which test and staging systems are needed and how are they connected. • Introduce best practices and recommendations for organizing development teams

and handling concurrent development efforts on the test and staging systems • Provide a specific case scenario example - illustrating how to use RAD v. 7.5 to

move development artifacts from RAD v. 7.5 into a Portal 6.1 Environment

3.1 Portal Environment configurations After reading this section you will be able to understand the different kinds of portal environment configurations. We will describe the typical environments used on a Portal project including development, staging and production servers. On a typical portal project, a solution is created on one system called the development environment. This solution is later tested on a different system called Quality Control (QA). Depending on the resources available QA can be combined with User Testing (UAT) and performance testing on a different environment called staging. The final solution is deployed to a system called the production environment. On the River Bend project, a decision was made to have only three sets of servers. A development stand-alone Portal, a cluster environment for testing (staging) and a production cluster for production. See the picture below for details.

- 41 -

River Bend Environments

PRODUCTION

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

STAGING

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

DEVELOPMENT

Database LDAP

WebSphere Portal

Firewall

WebSphereApplication Server

River Bend Environments

PRODUCTION

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

STAGING

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

DEVELOPMENT

Database LDAP

WebSphere Portal

Firewall

WebSphereApplication Server

Figure X RiverBend Server Environments During the development cycle of the River Bend portal, multiple releases are created on the development server and brought into the staging and production environments using the XML scripting tool (XMLAccess), Release Manager and the new Site Manager portlet application. (Note: – greater detail on using each of these tools, together with a specific example of how to use the tools is provided in a later section of this document.)

Development system New Portal artifacts are created by developers using an Integrated Development Environment (IDE) like Rational Application Developer 7.5. The developers then perform unit tests on their IDE environments. At a later point, code is deployed to a server for a system integration test with other elements of the portal solution. This system is called the development server. It is usually a sandbox type of environment where developers deploy the most recent code artifacts. Code is posted to a code management system where it is tagged and version for accountability. The build master deploys the new code artifacts to the development server using tools like the XML scripting tool or the Portal Administrator User Interface (UI) screens.

Staging System The staging system configuration is derived from the production environment. It typically has the same operating system and hardware specifications. It is important that the staging and production environments share as much as possible the following characteristics:

• Directories (LDAP) • Application and portal databases

- 42 -

• Web server configurations

Production System This is the most important system. The portal solution is deployed here to meet the business requirements. There are some critical considerations on system availability and performance. It is usually a clustered environment. It is a common practice to restrict access to this environment. Only the build master can deploy new code using automated scripts or build tools like Release builder and Site Management.

3.2 Development and build process This section will explain the steps necessary to create a code release. It will explain the tools used by the development team to manage code artifacts. It will also discuss the main issues encountered when executing concurrent development efforts.

Portal release lifecycle In general the development team creates a portal solution, tests and refines the solution and then moves the solution to a production environment. See the figure below.

Build Release Cycle

PortalDeveloper

DevelopmentServer

BuildServer

SourceCode

Repository

DevelopmentBuild

StagingServer

ProductionServer

DevelopmentIntegration

Test

User AcceptanceTest & QA

Release

ContentCreator

BuildMaster

CODE

SCRIPTS

CONTENT

Build Release Cycle

PortalDeveloper

DevelopmentServer

BuildServer

SourceCode

Repository

DevelopmentBuild

StagingServer

ProductionServer

DevelopmentIntegration

Test

User AcceptanceTest & QA

Release

ContentCreator

BuildMaster

CODE

SCRIPTS

CONTENT

Figure X Portal Release lifecycle. On the River Bend project we implemented the following procedure: The River Bend team developed a Portal solution that met the business requirements using agile development practices. The initial unit test was performed on the developers’ workstations. Once the code was deemed defect free, it was checked in into the source code repository. A build was created on the development server and deployed to the development environment for system integration test.

- 43 -

After completing the integration test, the build was deployed to the staging server for user acceptance test and quality control. Once the build was defect free and the customer successfully completed the test cases, the code was deployed to production for use by the RiverBend customers. There are great benefits of having a build and deploy process in place to manage your development efforts. These benefits include having deployable code that is made up of the right code level as well as traceability and repeatability of the entire build process.

Code management tools There are several tools that can be used to manage the source code produced by the development team. The most popular are open source tools like CVS and Subversion. In the River Bend project we used IBM Rational Clearcase.

CVS Concurrent Versions System (CVS) is a version control system. It is an important component of Source Configuration Management (SCM). It can be used to track of all work and all changes in a set of portal code artifacts. CVS is very popular with Open Source development teams. CVS is released under the GNU General Public License.

Subversion Subversion (SVN) is another version control system. It was initially created by CollabNet in 2000. It can be used to maintain current and historical versions of files such as portal artifact code. SVN goal is to be a mostly-compatible successor to CVS.

IBM Rational ClearCase Used by the River Bend developers, this tool allows for easy integration with the Rational suite including Rational Application Developer 7.5. Rational ClearCase is a software tool for revision control of source code and other software development assets. ClearCase can run on several platforms including MS Windows, Unix and Linux. It can handle large binary objects, large number of files and large repository sizes. ClearCase can handle branching, labeling and versioning of directories.

Strategies for concurrent development Having a build process will allow your developers to guarantee that code is checked in, stored and versioned by all the team members.

- 44 -

Versioning and tagging It is considered a best practice to have a set of development standards and templates for design and implementation guidance for the development team. Code build versions can be tagged in RAD 7.5, but this process can also be done with CVS commands directly. It is considered a best practice to restrict this task to just a few individuals, such as the build master and maybe a backup technician, in order to get consistent version names. An example is shown below on how to tag a recent branch from the HEAD trunk: Browse to HEAD and then right click. Select Tag as version from the menu

Enter the version name in the dialog box, be careful not to check "Move tag if it already exists"

- 45 -

Different teams use different version naming standards. The tagging versioning strategy used on the RiverBend project was determined as follows:

“- va_b_c” Where:

• a is a major release number. It only changes when a major milestone is accomplished.

• b is a number for a minor iteration. It is usually used for testing purposes. • c represents a patch to a minor iteration. It is usually created from a branch and

used only when necessary. These numbers start from zero and they are incremented as needed. There are no restrictions on the number of digits for each set of numbers.

Branching There are occasions where an emergency fix is needed or not all portal artifacts are completed by a certain deployment date. Branching is the duplication of code under revision control in such a way that the newly created branch has initially the same contents as the version that was branched off. Development can happen in parallel along both branches. Branching implies the ability to merge the code differences on a branch back to its parent branch. Usually the changes are merged back to the head (trunk) branch. On the River Bend we had two branches for static content stored in Web Content Management (WCM).

3. 3 Using Rational Application Developer v. 7.5 In the following section, we highlight a specific Portal development tool, Rational Application Developer v. 7.5 Rational Application Developer is a comprehensive integrated development environment built on the Eclipse open source platform. Application Developer accelerates the creation of portal themes, skins and applications by providing visual portal development tools and WebSphere Portal test environments.

Portal development overview A portal is a J2EE Web application that provides an interactive framework where developers can associate many portlet applications. The term portal is also used to refer to the site that contains these applications.

- 46 -

You can use the Rational Application Developer to create, customize, test, debug, and deploy your portal. The tool that allows you to develop the appearance, navigation, and content of your portal is called Portal Designer. Portal development support is provided for WebSphere Portal 6.x releases.

Portal tools for developing portals A portal is essentially a J2EE Web application. It provides an aggregation framework where developers can associate many portlets and portlet applications via one or more portal pages. Application Developer includes several new portal site creation tools that enable you to visually customize portal page layout, themes, skins, and navigation.

Enable portal development capability By default, Application Developer portal development capability is not enabled. To enable portal development capability, perform these steps: 1. Select Window → Preferences. 2. In the Preferences dialog, expand General → Capabilities and click Advanced 3. In the Advanced dialog, expand Web Developer (advanced), select Portal Development and click OK. 4. Click OK in the Preferences dialog and portal development is enabled.

- 47 -

Figure 3.3 - 1. Enable Portal development feature

Portal projects Development of a portal application in the workbench requires a portal project, which can be imported from WebSphere Portal or created with the New Portal Project wizard. A portal project is the file collection that you create for both the structural and aesthetic framework of your portal. It consists of a layout, themes, skins, and portlets.

The recommended method for creating a portal project is to import a portal site from a WebSphere Portal server. This ensures that you begin working with the most current portal configuration for your version of WebSphere Portal.

- 48 -

Portal import wizard One way to create a new Portal project is to import an existing portal site from a WebSphere Portal server into Application Developer. Importing is also useful for updating the configuration of a project that already exists in Application Developer. The portal site configuration on WebSphere Portal server contains the following resources: the global settings, the resource definitions, the portal content tree, and the page layout. Importing these resources from WebSphere Portal server to Application Developer overwrites duplicate resources within the existing Portal project. Non-duplicate resources from the server configuration are copied into the existing Portal project. Likewise, resources that are unique to the Portal project are not affected by the import. Application Developer uses the XML configuration interface to import a server configuration, and optionally retrieves files from installedApps/node/wps.ear of the Application Server installation. These files include the JSP, CSS, and image files for themes and skins. When creating a new Portal project, retrieving files is mandatory. To retrieve files, Application Developer must have access to this directory, as specified when you define a new server for this project.

Portal Project wizard You can use Portal Project wizard to create a portal project within Application Developer. During this process, you are able to:

• Specify a project name. • Select the version of the Portal server. • Choose a default theme. • Choose a default skin for the chosen theme.

To create a new Portal Project, do these steps: 1. Select File → New → Project → Portal. 2. Expand Portal and select Portal Project, Click Next. 3. In the New Portal Project dialog, enter RiverBend_1104 in the Project Name field.

- 49 -

Figure 3.3 - 2. Portal Project wizard

- 50 -

Figure 3.3 - 3. New Portal Project

• In the Select Theme dialog, select the default theme (IBM) and click Next. • In the Select Skin dialog, select the default skin (IBM) and click Finish. • Click Yes in the Open Associated Perspective dialog. The Portal Designer editor

is opened with the selected theme and skin.

Portal Designer Application Developer allows for editing both the graphic design and portlet layout within your portal. Portal Designer is the Workbench interface that you see upon opening a Portal project.

- 51 -

When using Portal Designer, the portal page layout can be altered. The layout refers to the number of content areas within a page and the number of portlets within those content areas. Page content includes rows, columns, URLs, and portlets. In terms of portal layout and appearance, you can think of Portal Designer as a What-You-See-Is-What-You-Get (WYSIWYG) editor. It will render graphic interface items such as themes, skins, and page layouts.

Figure 3.3 - 4. Portal Designer editor

Deploying a portal Deployment refers to the process of moving your portal project from your workspace to a staging or production server. You can deploy your project to the server automatically (Deploy), or you can move it manually (Export).

Portlet development overview The Rational Application Developer includes tools designed to help you develop portlet applications for WebSphere Portal 6.0, and later.

Portlet project Portlet projects are used for developing portlet applications in the product workbench. These projects contain all of the necessary resources for testing, debugging, coding, or deploying a portlet. To create a portlet application, you must either create a portlet project using the New Portlet Project wizard, or import a portlet WAR file using the Import wizard.

RiverBend Portlet Project The following topics demonstrate how the RiverBend portlet project is created in Rational Application Developer v7.5.

- 52 -

To create portlet project, click File –> New -> Project -> select Portlet Project

Figure 3.3 - 5. New Portlet Project

In the New Portlet Project dialog, enter RiverBend_1104 in the Project Name field, select JSR 168 Portlet or JSR 286 Portlet as Portlet API, and specify a name and type for the portlet if you are going to create a portlet for this project, see Figure 3.3-6.

- 53 -

Figure 3.3-6 New Porlet Project details

Then you can define the action handling and preference handling of the portlet after click Next on the screen, see Figure 3.3-7:

- 54 -

Figure 3.3-7. New Portlet Project – Action and Preferences handling

Then click on Finish to complete the Portlet Project creation. Next you need to add the business logic to the portlets. After you complete the portlet application development, you can define a WebSphere Portal Server in Rational Application Developer to test the application.

Test RiverBend Portlet Application To test the portlet application, a WebSphere Portal Server has to be defined in the workspace. It can be a local server or a remote server.

- 55 -

In the RiverBend project, Rational Application Developerv7.5 and WebSphere Portal Server v6.1 are located on the different physical servers, therefore a remote server needs to be defined.

Define WebSphere Portal Server To set up your connection to the WebSphere Portal server:

1. Open the Servers view by clicking Window > Show View > Servers 2. Right-click and select New > Server. 3. For the Server's host name, enter one of the following:

o If in a local test environment, localhost should already be there by default. If not, type localhost.

o If on a remote test server, type the host name or IP address of your WebSphere Portal remote test server. Wps01.itso.ibm.com is the remote host for the development portal server v6.1 in RiverBend project.

4. Select the appropriate WebSphere Portal from the server type list. Select the corresponding Server runtime environment, and then click Next.

- 56 -

Figure 3.3 - 8. Define a new server

5. On the WebSphere Settings page, specify the appropriate server connection type

and admin port for your networking environment. Specify the administrator ID and password for the portal server, click Next. (see Figure 3.3 - 9)

- 57 -

Figure 3.3- 9. Define a new Server - Websphere Settings

7. On the Websphere Portal settings page, specify the Install Location. (Note: that this is only needed in instances where the Deploy action will be used on Portal or Portlet Projects, see Figure 3.3 - 10).

- 58 -

Figure 3.3 - 10. Define a new server – WebSphere Portal settings

8. On Properties Publishing Settings page, specify the location of the application folder (<portal-install location>\PortalServer\shared\app). Note: that this is only needed in instances where the Deploy action will be used on Portal or Portlet Projects, see Figure 3.3 - 11.

- 59 -

Figure 3.3 - 11. Define a new server – Properties Publishing settings

9. Specify the Websphere Portal administrator user ID and password. (If you want to use the automatic login to the portal, select the Enable Automatic Login check box.) Then click Finish.

Note: If you need to test or debug with multiple users on the same remote portal server, you need to create users that will access the portlets being tested through the Portal Administration page on the remote server. Testing or debugging a portlet on a remote server automatically adds the required permissions. Every user must use his/her own user ID. Otherwise, the portlet application that you are previewing may be accidentally uninstalled by someone whose user ID is the same as yours. Or, your preview page may be accidentally updated, if the label is also the same

- 60 -

Test RiverBend Portlet application on the server To test a portlet project on a remote WebSphere Portal server:

1. From the Project Explorer view, highlight the RiverBend_1104 portlet project and select Run As > Run on Server.

Figure 3.3 - 12. Run RiverBend portlet project on the server

2. To use an existing server definition, select Choose an existing server and choose the correct remote server version for your project from the list.

- 61 -

Figure 3.3 - 13. Run on Server details

3. Click Finish. After the server starts and the portal is deployed, the Web browser that you defined opens to the URL of the portal application on the remote server.

Export RiverBend portlet project

Exporting a portlet project creates a WAR file that can be installed on a WebSphere

Portal server. To export a WAR file for a portlet project, from the Project Explorer view, right-click the portlet project and select Export > WAR file.

- 62 -

Figure 3.3 -14 Export RiverBend portlet project

Figure 3.3 -14 shows RiverBend portlet project is exported as a war file from the workbench. The portlet WAR file is then installed on the remote WebSphere Portal server through the Portal GUI administrative interface.

- 63 -

Topic 4. - XMLAccess, Release Builder, Site Management – an overview of the tools and specific example using each one

Objective of this section The purpose of this section within the wiki is the following:

• How to apply this to the flow of data through the development/test/staging/prod phases,

• Describing each of the transfer tools – what they are and in which cases they are appropriate to use,

• Specific case example - How to do the transfer using each of the specific tools

4.1 Deployment and build process This section describes the deployment and build processes used on most Portal projects. The build is the process of creating a set of portal artifacts to meet the business requirements on a portal project. It is an important activity in the release cycle of a portal project. This build process compiles the code and generates the deployable packages (war files) containing the portal project solution artifacts. The entire build process should be repeatable and traceable. The build should be composed of the correct code version and defect free. There are two types of build processes:

• Local build – A developer using an IDE like Rational Developer 7.5 builds code on her workstation using ANT or Mavens scripts. On RAD 7.5 there is integrated Test environment where code can be tested.

• Server Build – Developer checks in the code to the code management system, the

build master extracts the code from version control and builds the deployable package using ANT or Maven scripts. This process also includes any dependent JAR files and packages them accordingly.

In the River Bend project, the build master used the xml scripting tool (XML Access), Release builder and the Site Management portlet available on Portal V6.1

- 64 -

4.2 a - XML Access The XML configuration interface, also known as XML Access, is accessed using a command line tool. This command line client is a small separate script program that connects to a Portal server using an HTTP connection. It can be used remotely. The XML syntax is as follows: Xmlaccess –in Infile.xm –user user –pwd password –url portalConfigURL –out resultfile.xml The XML configuration interface is used to process portal resources but not portal actions or tasks. On the River Bend project we used XML access to process existing portal resources like pages and portlets. The River Bend build master also used XML Access to produce the XML files needed for the Release builder tool.

4.2 b - Release Builder Tool The Release Builder tool is used to compare two XML Access files, determine their differences and produce a new script that can be used to synchronize the two environments. Release Builder is valuable to identify portal artifacts that are deployed to the production environment but are not longer in the stage environment.

4.2 c - Site Management Tool Site Management is a new feature in WebSphere Portal version 6.1. It provides an easy way to manage the individual pages, groups of page, artifacts, and properties that make up those pages to move around between different Portal environments. For instance, you can create pages, labels, and URLs on a source server and publish them to other servers by using the Resource Manager portlet. Once the page is modified, re-published and re-promoted, the previous promoted page becomes a version page, which makes it possible to rollback if it is needed. The lifecycle of the site management is described in the following diagram:

- 65 -

Figure 4.2c - 1. Site Management lifecycle In section 4.3c, we discuss a specific example of how to use Site Management to perform a Portal Transfer.

4.2 d – Which Tool is appropriate for which type of situation In the section above, we have provided an overview of each of the tools which can be used to move Portal Configuration entities between environments. The following points should be taken into consideration:

• For a complete transfer, (e.g. – an initial transfer from development to staging and to production, ) we would use XMLAccess, because we don’t need the differential option that Release Builder provides.

• But, once you have already done the first complete transfer, you would want to transfer only what is new, deleted, changed, this is when we use ReleaseBuilder. The differential option would create a XML with the recently created, removed, changed items.

• Finally, the new Site Management portlet you to transfer a specific page or page hierarchy

The figure below, together with the following table, is provided to give a better understanding about which tool may be most applicable for a specific situation.

- 66 -

XML Access

Release Builder

Site Management

Scope of Transfer / Changes

Dev Staging Production

Changes at the page level

Comparing differential Between XML Files

Capable of transferring the entire configuration

Import the differential XML file

Figure – understanding the capabilities and scope of each of the tools for transferring release elements

- 67 -

Comparing Configuration Management Tools

Partial Updates(for pages, labels andURLs)

DifferentialUpdate

Full Transfer

Most Suitable Use

Allow you to publish, promote or demote a page, label or URL.

Pages, Labels andURLs

Site Management

Recommendation to stop Portal and avoidusing it on production

The same as XMLAccess

Release Builder

Portal must berunning

All portal resources, BUT: WAR files, themepolicies, themeand skin files

XML Access

Other Considerations

Transfers following artifacts

Table – comparison of the tools for managing releases

4.3a Specific Example - Portal Transfer with XMLAccess

Transferring a complete configuration using XML Configuration Interface The following example describes a simple case of moving a complete configuration (not including users) from one portal to another. Example case: Move a configuration from a development portal (named wps01) to a staging portal (named wps02) using the XML configuration interface.

Export the configuration from the source machine Once you have your development machine loaded with pages and portlets, it is time to export them using the XML configuration Interface.

1. Change to the following directory:

<PortalServer>\doc\xml-samples\

- 68 -

2. Copy the file ExportRelease.xml to <PortalServer>/bin/ 3. Change to the following directory:

<PortalServer>/bin/

4. Export the configuration from the development server by entering the following command:

xmlaccess.bat -in ExportRelease.xml -user <Portal_Admin_ID> -pwd <Portal_Admin_Password> -url http://<portal_hostname>.ibm.com:port/wps/config -out <filename>.xml Example: xmlaccess.bat -in ExportRelease.xml -user wpsadmin -pwd wpsadmin -url http://wps01.itso.ibm.com:10040/wps/config -out wps01_export.xml

5. The export is completed once the message “EJPXB0020I: The request was processed successfully on the server” is displayed:

6. The command above will generate a file called wps01_export.xml under the <PortalServer>/bin directory. Copy this file to the same directory in the target server.

7. Change to <wp_profile>/PortalServer/deployed/

8. Copy the entire <wp_profile>/PortalServer/deployed/archive directory from the source to the target machine, because in general, all deployed WAR files are copied to this directory.

- 69 -

Import the configuration in the target machine

Empty Portal task When you transfer the configuration for the first time, the target server (wps02) must be empty. Empty means that no portlets have been installed and no pages have been created.

You have the option to turn a full Portal installation into an empty portal by running the ‘empty-portal’ task.

Run <wp_profile_root>/ConfigEngine/ConfigEngine.sh empty-portal

The task has been completed successfully when you see the BUILD SUCCESSFUL message as shown in the picture below:

Changing portlet URLs Verify that all URLs in the file wps01_export.xml are valid. Search by the <url> tag in the exported file and make sure that the path specified on this file exists in the target machine. Example: <url>file://localhost/$user_install_root$/PortalServer/deployed/archive/com.ibm.workplace.cdo.portal/appCatalogPortlet.war</url> The target machine must have the file appCatalogPortlet.war in the following location:

<wp_profile>/PortalServer/deployed/archive/com.ibm.workplace.cdo.portal/appCatalogPortlet.war

- 70 -

For this reason, it is easier if you just copy the entire <wp_profile>/PortalServer/deployed/archive directory from the source to the target machine, because in general, all deployed WAR files are copied to this directory.

Predeployed portlets If you have installed predeployed portlets in the source server, you will have to deploy them again in the target server. It is preferable that you deploy them in the same location as you did in the source machine, this will avoid changes to the exported XML file. Aleternatively, if you have not used the same directory name, do the following:

1. Edit the file wps01_export.xml which is our XML export file. 2. Search for all instances of the word “predeployed”, you will see something like

that: XML config for a predeployed portlet <web-app action="update" active="true" domain="rel" objectid="1_CGAH47L00G7AF02N7E64FG20G4" predeployed="true" removable="true" uid="com.ibm.wps.portlets.webPage.WebPagePortlet"> <url>file://localhost/$app_install_root$/wps01/PA_WebPage.ear/webpage.war</url> <context-root>/wps/PA_WebPage</context-root> <display-name>webpage_war</display-name> <servlet action="update" active="true" domain="rel" name="WebPagePortlet.$appuid.com.ibm.wps.portlets.webPage.WebPagePortlet.1" objectid="V_CGAH47L00G7AF02N7E64FG20G6" remote-cache-dynamic="false"/> <portlet-app action="update" active="true" domain="rel" name="WebPagePortlet" objectid="2_CGAH47L00G7AF02N7E64FG20G2" uid="com.ibm.wps.portlets.webPage.WebPagePortlet.1"> <portlet action="update" active="true" defaultlocale="en" domain="rel" name="WebPagePortlet" objectid="3_CGAH47L00G7AF02N7E64FG20G1" provided="false" servletref="V_CGAH47L00G7AF02N7E64FG20G6"> </portlet> </portlet-app> </web-app>

3. Verify the <url> tag value and change it to match the path of this predeployed

portlet in the target server

The XML above is showing the following URL:

file://localhost/$app_install_root$/wps01/PA_WebPage.ear/webpage.war

The $app_install_root$ in this case is the installedApps directory of the Portal profile. Example: <WebSphere>/wp_profile/installedApps/wps01/PA_WebPage.ear/webpage.war If you have installed the predeployed portlet in the default directory, you will have to change the URL to look like that:

- 71 -

file://localhost/$app_install_root$/wps02/PA_WebPage.ear/webpage.war

Importing the Theme Policy If you have created a customized theme policy on your development server you will need to transfer it to the staging server. Refer to the appropriate section in this wiki for instructions on how to do this.

Importing the Theme You might have to import the theme in use by your development server. If you have created a customized theme, refer to the appropriate section in this wiki to transfer it to the staging server.

Importing the configuration 1. If you have not already done so, copy the exported file, wps01_export.xml,

from the source machine to the target machine in the following directory:

<PortalServer>/bin/

2. Import the configuration in the staging server by entering the following

command: xmlaccess.bat -in wps01_export.xml -user <Portal_Admin_ID> -pwd <Portal_Admin_Password> -url http://<portal_hostname>.ibm.com:port/wps/config

Example: xmlaccess.bat -in wps01_export.xml -user wpsadmin -pwd wpsadmin -url http://wps02.itso.ibm.com:10040/wps/config

3. The import is completed successfully once the message “<status element=”all” result=”ok”/> is displayed.

- 72 -

4. If you have a clustered environment, you will see several warning messages like this:

<status element="[web-app 1_CGAH47L008PG002N6FPUR118E5]" rsult="warning"> <message id="EJPPH0049W">com.ibm.wps.command.xml.XmlCommandException: EJPPH0049W: Automatic node synchronization is enabled for node [wps02, wps0202]. However the portlet application RiverBend will not be started in the Application Server. Manually start the application after all nodes were synchronized. [web-app 1_CGAH47L008PG002N6FPUR118E5]</message>

</status>

5. If you have manual synchronization enabled, synchronize all nodes from this

cluster, and then, manually start all the portlet applications using the Deployment Manager Administrative Console.

6. If you have a clustered environment, run the following command to activate the

deployed portlets:

<wp_profile_root>/ConfigEngine/ConfigEngine.sh activate-portlets

7. The task has been completed successfully when you see the BUILD SUCCESSFUL message

8. Restart Portal, if it is a clustered environment, restart the entire cluster.

9. The staging server is now ready to use.

Note: You can use the same procedure to transfer data from staging to production. When you have a clustered environment, you can choose one of the cluster members to be the

- 73 -

target server. Once you synchronize and/or restart the Cluster, the changes will be propagated to all cluster members.

4.3b Specific Example - Portal Transfer with Release Builder

Transferring a partial configuration using Release Builder The following example describes a simple case of copying parts of a configuration from one portal to another. Example case: Copy a set of pages and portlets from a staging server (named wps02) to a production server (named wps03) using the differential process of Release Builder. Before running these steps, you will have to follow the procedure of transferring a complete configuration. Refer to the appropriate section in this wiki for instructions on how to do this.

Build the first release of the staging (source) machine Once you have your staging machine loaded with pages and portlets, it is time to build the first release using Release Builder. The picture below shows the actual release:

- 74 -

1. Change to the following directory:

<PortalServer>\doc\xml-samples\

2. Copy the file ExportRelease.xml to <PortalServer>/bin/

3. Change to the following directory:

<PortalServer>/bin/

4. Export the configuration from the staging server by entering the following command:

xmlaccess.bat -in ExportRelease.xml -user <Portal_Admin_ID> -pwd <Portal_Admin_Password> -url http://<portal_hostname>.ibm.com:port/wps/config -out <filename>.xml Example: xmlaccess.bat -in ExportRelease.xml -user wpsadmin -pwd wpsadmin -url http://wps01.itso.ibm.com:10040/wps/config -out wps01_release01.xml

- 75 -

5. The export is completed once the message “EJPXB0020I: The request was processed successfully on the server” is displayed:

6. The command above will generate a file called wps01_release01.xml under <PortalServer>/bin directory, copy it to the target server in the same directory.

Build the second release of the staging (source) machine After the first release has been created, the Portal Administrator may have created new pages and portlets on the staging server. We have to create a XML file containing just the new pages and portlets, so we can import it in the production server. The picture below shows the second release, the differences are:

1. Page “Spiced Tea” under “Teas” page has been removed;

2. Page “Arabica Coffee” page has been created under “Coffees”, this page contains a Local Rendering Portlet which has been already installed;

- 76 -

3. Follow the same steps you did before to create the second release. This time you will use a different file name for the output, wps01_release02.xml: Example: xmlaccess.bat -in ExportRelease.xml -user wpsadmin -pwd wpsadmin -url http://wps01.itso.ibm.com:10040/wps/config -out wps01_release02.xml

Creating a differential XML from both releases Run this procedure on the staging server.

1. Stop the Portal server on the staging system. This is recommended during the execution of Release Builder.

2. Change to <PortalServer>/bin

3. Run the following command in order to generate a XML containing the additions

and deletions configuration file:

- 77 -

releasebuilder.bat -inOld wps01_release01.xml -inNew wps01_release02.xml -out differences_wps01.xml

The command line above will create a file called “differences_wps01.xml” which contains just what has been done recently on the staging machine.

4. Copy this file to the target server’s <PortalServer>/bin directory.

5. Restart the Portal server on the staging server

Import the XML configuration containing the differences If the XML includes new portlets, make sure you copy the war files to the archive directory into <wp_profile>/PortalServer/deployed/archive

Predeployed portlets If you have installed predeployed portlets in the source server, you will have to deploy them again in the target server. It is preferable that you deploy them in the same location as you did in the source machine, this will avoid changes to the exported XML file. Alternatively, if you have not used the same directory name, do the following:

1. Edit the file differences_wps01.xml which is our XML export file.

2. Search for all instances of the word “predeployed”, you will see something like that:

XML config for a predeployed portlet <web-app action="update" active="true" domain="rel" objectid="1_CGAH47L00G7AF02N7E64FG20G4" predeployed="true" removable="true" uid="com.ibm.wps.portlets.webPage.WebPagePortlet"> <url>file://localhost/$app_install_root$/wps01/PA_WebPage.ear/webpage.war</url> <context-root>/wps/PA_WebPage</context-root> <display-name>webpage_war</display-name> <servlet action="update" active="true" domain="rel" name="WebPagePortlet.$appuid.com.ibm.wps.portlets.webPage.WebPagePortlet.1" objectid="V_CGAH47L00G7AF02N7E64FG20G6" remote-cache-dynamic="false"/> <portlet-app action="update" active="true" domain="rel" name="WebPagePortlet" objectid="2_CGAH47L00G7AF02N7E64FG20G2" uid="com.ibm.wps.portlets.webPage.WebPagePortlet.1"> <portlet action="update" active="true" defaultlocale="en" domain="rel" name="WebPagePortlet" objectid="3_CGAH47L00G7AF02N7E64FG20G1" provided="false" servletref="V_CGAH47L00G7AF02N7E64FG20G6"> </portlet> </portlet-app> </web-app>

3. Verify the <url> tag value and change it to match the path of this predeployed

portlet in the target server

- 78 -

The XML above is showing the following URL:

file://localhost/$app_install_root$/wps01/PA_WebPage.ear/webpage.war

The $app_install_root$ in this case is the installedApps directory of the Portal profile. Example:

<WebSphere>/wp_profile/installedApps/wps01/PA_WebPage.ear/webpage.war

If you have installed the predeployed portlet in the default directory, you will have to change the URL to look like that:

file://localhost/$app_install_root$/wps02/PA_WebPage.ear/webpage.war

Each of the pages used in this example contain a Local Rendering Portlet. In this case, the portlet is already installed, so, there is no need to copy the war file as mentioned before.

1. Import the configuration containing the new pages and portlets in the production server by entering the following command: xmlaccess.bat -in differences_wps01.xml -user <Portal_Admin_ID> -pwd <Portal_Admin_Password> -url http://<portal_hostname>.ibm.com:port/wps/config Example: xmlaccess.bat -in differences_wps01.xml -user wpsadmin -pwd wpsadmin -url http://wps02.itso.ibm.com:10040/wps/config

2. The import is completed successfully once the message “<status

element=”all” result=”ok”/> is displayed:

- 79 -

3. The production server now contains the same release as the staging server. Note: You can use the same procedure to transfer data from development to staging. When you have a clustered environment, you can choose one of the cluster members to be the target server. Once you synchronize and/or restart the Cluster, the changes will be propagated to all cluster members.

4.3c Specific Example - Portal Transfer using Site Management Site Management features provided by WebSphere Portal v6.1 make managing multiple portal deployments easier. Portal administrators can use Site Management and the Resource Manager portlet to develop and test a portal page on a test server, then copy the page to a target server for review and later promotion to a live page. Once you publish the page to a target server where only a selected group of users can preview and do additional test before promoting the page to all users and groups with the appropriate access rights. After the page is modified , republished and re-promoted, the previous promoted page becomes a version page. The demote function makes the page no longer visible in the target server if a rollback is needed. The following example illustrates how to use Site Management to perform a portal transfer.

Enabling remote access to your servers The portal site management publish feature requires at least two portal systems: a source system, where you create new pages that you need to publish, and a target system, where you make the new pages visible to portal users. You can also use one server with two or more virtual portals for your source and target systems. The Resource Manager portlet can display the contents of the systems. By default, the portal server is pre-configured to allow remote access. If you have a portal cluster, you need to run the enable-http-basic-auth-tai-sitemgmt task before you start managing your site. A WebSphere Application Server Trust Association Interceptor (TAI) is used to authorize access to the servers. Note: Individual virtual portals on a single portal server do not require the enable-http-basic-auth-tai-sitemgmt task to be run more than once. In this River Bend project, the development server is a standalone portal server, both staging and production environments are vertical portal clusters with two portal instances installed on the same physical Windows 2003 server. In order to manage the sites, the task enable-http-basic-auth-tai-sitemgmt needs to be run on the staging and production servers for each portal instance, details of running this task are described next:

- 80 -

Open a command prompt and change to the directory where WebSphere Portal ConfigEngine is installed (wp_profile_root\configengine on windows) and issue the following command:

ConfigEngine.bat enable-http-basic-auth-tai-sitemgmt -DPortalAdminPwd=password -DWasPassword=password

Use -DPortalAdminPwd=password -DWasPassword=password to specify the portal and WebSphere Application Server IDs passwords. Note: This task uses the settings in the file wkplc_comp.properties to configure the TAI. Although the TAI settings are pre-configured to work without requiring adjustment, you can change the settings before running the task if you need to configure the TAI differently. The build successful messages of this task showed as following: BUILD SUCCESSFUL Total time: 1 minute 0 seconds isIseries currently set to: null uploading registry Created admin client: com.ibm.ws.management.AdminClientImpl@7f5e7f5e Created config Service Proxy: com.ibm.websphere.management.configservice.ConfigS erviceProxy@3f2a3f2a CELL: wps02Cell01 Websphere:_Websphere_Config_Data_Type=Registry,_Websphere_Config_Data_Id=cells/wps02Cell01|registry.xml#Registry_1225855618625,_WEBSPHERE_CONFIG_SESSION=anonymous1225980772093 HTTPBasicAuthTAI setting can be verified through WebSphere Application Server administrative console, see Figure 4.3c – 1.

- 81 -

Figure 4.3c – 1 Trust association setting Important: After this task runs successfully on each portal instance, the deployment manager server, nodeagents and portal servers in the cluster environment need to be stopped and restarted for the TAI configuration settings to take effect. If any of the servers are enabled for Secure Socket Layer (SSL), you must perform additional steps on the server where you will manage your site. Please refer to the WebSphere Portal Server Infocenter for details on this topic. http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp

Managing your servers

Before you begin to manage your site using the Site Management page, you must add the source and target servers to the Resource Manager portlet. After adding the servers to the portlet, you can edit and remove servers and manage access to the servers.

You must be an administrator to use the site management functions. To manage the servers, select Administration > Site Management > Manage Servers.

- 82 -

Figure 4.3.c - 2. Manage Servers

1. Add a new server First you need to add a new server, click Manage servers > Add new server.

Figure 4.3c - 3. Add a new server Enter the fully qualified Host name for the server and the port. You can accept the default path, for example:/wps/mycontenthandler as the server path. Then assign a unique name for the server and check the Use Secure Sockets Layer option if the server is set up for SSL.

- 83 -

Note: If you configure a virtual portal, then the path is /wps/mycontenthandler/vpid where vpid is the URL context of the virtual portal. First add the development server as a source server and assign a unique name: Local

Figure 4.3c - 4. Add the source server Then add the staging server as a target server and assign a unique name: Staging

Figure 4.3c - 5. Add the target server 2. Manage server access Use the Manage server access option to provide or update the login credentials to servers that you are managing. Click Manage servers and then select Manage server access.

- 84 -

======================================== Figure 4.3c - 6. Manage server access Select the server that you want to access from the drop-down menu, and enter the User name and Password for the server, click Save to save the information, or click Done to exit without saving the information.

Figure 4.3c - 7. Manage server accounts You can also edit or remove a server using the Manage Servers option.

Publishing your page After you have created and tested your content, which could be a page, a label, or a URL, you can publish it to a target server. You can perform the publish task by using the Resource Manager portlet on the Site Management page, or by using the Portal Scripting Interface. This topic describes publishing through the Resource Manager portlet.

1. Create and test a page on your source server.

- 85 -

The following information, or referenced items, are published if they are included in a page:

• Unique names • Page properties • Page layout • Page metadata • Friendly URLs • References to portlets on the page

Note: The same portlets with the same unique name as on the source portal must also exist on your target portal. References to JSR portlets and to IBM portlet without binary parameters are supported.

• Shared or default portlet preferences • Portlet wires • Advanced options under Edit page properties.

Limitations:

• You can only publish pages that have a unique name. • The following items that a page can reference do not get published:

o Page permissions or access controls o URL mappings o Derived pages o Composite applications o Web Content Management content or libraries o Private resources o Private wires o Personalized portlet preferences o Portlets or portlet WAR files. You can publish references to portlets only

if the portlets exist on the target server. o Personalization rules. These must exist on the target server.

• Site management does not support the merge of multiple publish events from different users. The last publish process overwrites previous publish versions.

• You can go back only one version on a publish, promote, and demote scenario. If you want to go back farther than that, you need to create backups of the versions that you might want to go back to. You can do this by using the XML configuration interface.

• Site management publishing does not support cross page wires.

2. Select a server

Select a source server and a target server before publishing the page.

- 86 -

Click Administration > Site Management, select the server from the pull-down list.

Figure 4.3c - 8. Select a source and a target server for site management

3. Publish a page/pages

You can publish a single page or label or the entire page or label hierarchy from a source server to the target server.

Right click on the page or label and select Publish to > servername.

- 87 -

========================================================== Figure 4.3c - 9. Publish a page

As Figure 4.3c-9 shows, River Bend was selected to be published to the staging server.

Figure 4.3c - 10. Publish Page details

- 88 -

On the publish page details screen (see Figure 4.3c-10), select the Page radio button to publish a single page or label. If this is a hierarchy that you want to publish, select the Entire subtree radio button. Enter the Parent page unique name, which is the unique name of the parent page on the target server. There is an optional field for Sibling page unique name, which is the unique name of the page that comes after the published page in the target server hierarchy.

A published page is created on the target server with a published sign ( ), see Figure 4.3c-11.

============================================================= Figure 4.3c - 11. A page is published on the target server

You can logon to the target server as a portal administrator to view the published page and verify that the page that you published is available on the server and is working as designed.

Notes:

1. Parent and sibling pages or portlets that you publish by using site management must have a unique name assigned to them on both the source and target servers. For a portlet the unique name must be the same on both the source and the target server. Make sure that when you create your page that you assign it a unique name; otherwise, you cannot publish the page to another server.

2. If the pages or portlets that you publish have existing personalization visibility rules associated with them, site management will publish the rule associations, but not the rules themselves. You must make sure that the same rules exist on both the source and target servers, and preserve the correct page-to-rule association.

- 89 -

3. Publishing a page into the public area of the portal is not supported. 4. When a page hierarchy that you publish contains a page that is marked private for

yourself on the source server, that private page is published as a public page on the target server. This also applies to private changes that you made to a page that you publish. When you publish that page, other users can see the page just the same as you with all private changes that you made to the page.

5. Pages that exist on the target server, but have not been created by a by site management publish step cannot be replaced by using the site management functionality. In such a scenario an error message is displayed.

6. Pages managed by site management must only be changed on the source server, not on the target server; otherwise the site management function may not work any more.

7. If two administrative users attempt to publish different versions of the same page at the same time, there is no support for merging these multiple publish actions. The last version of the page to be published is displayed. It overwrites other versions.

Providing reviewer access to a published page A special personalization rule is used to make a published page visible to a specific set of users, who will review the page before it is promoted. You can customize this rule to control which users can review the page. When you publish a page using the Site Management publish feature, or the JACL publish script, the page is copied from one portal system to another, or from one virtual portal to another. When the page is published but not yet promoted, it is not visible to all users and is hidden by a special personalization visibility rule named publishRule. By default, the publishRule visibility rule allows members of the Portal administrators (wpsadmins) group to see and review published pages that have not been promoted. This rule can be modified using the Personalization Rule Editor. To access Personalization Rule editor, from portal administrative console, click Applications > Content > Personalization > Business Rules, see Figure 4.3c-12.

- 90 -

Figure 4.3c - 12. publishrule details in Personalization Editor

Promoting your page Once the reviewers have reviewed the page, use the Site Management promote feature to move the page from the published (review) state to the promoted (live) state, where all users on the target server with the appropriate access rights can view the page.

To promote a page on the target server, click Administration > Site Management, then right click on the label or page or URL that you want to promote, then click Promote this page.

- 91 -

Figure 4.3c - 13. Promote a page

After the page is promoted, it shows a promoted sign ( )in front of the page within the Resource Manager Portlet panel, see Figure 4.3c-14.

Figure 4.3c - 14. The RiverBend page is promoted

- 92 -

If you promote a label or a URL, the promotion takes place without further prompting. When you promote a page or a page sub tree, and a page or sub tree with the same unique name exists already, you must choose a customization option, as described below.

• Promoting a single page on the target server If you promote a single page on the target server, you choose from the following options:

o And remove customization This option overwrites customized preferences on replaced pages.

o But preserve customization This option preserves customized preferences on replaced pages.

• Promoting a page sub tree on the target server If you promote a page sub tree on the target server, you choose from the following options:

o To add and update pages and remove customization This option adds and replaces pages and nodes on the target portal by those from the source portal and leaves nodes that are not affected unchanged. It overwrites customized preferences on replaced pages.

o To add and update pages but preserve customization This option adds and replaces pages and nodes on the target portal by those from the source portal and leaves nodes that are not affected unchanged. It preserves customized preferences on replaced pages.

o To create a duplicate sub tree and remove customization This option adds, replaces, and removes pages and nodes on the target portal to exactly match the sub tree of the source portal. It overwrites customized preferences on replaced pages.

o To create a duplicate sub tree but preserve customization This option adds, replaces, and removes pages and nodes on the target portal to exactly match the sub tree of the source portal. It preserves customized preferences on replaced pages.

If a promoted page with the same unique name exists already, the previously promoted page becomes the old version of the page. If an old version of the page with the same unique name exists already, that page is overwritten. Any personalization settings that were applied to the old page or portlet are retained and used by the new version of the page. Also, any URL references to the old page now point to the new page.

Republishing and promoting a page When you make changes to a promoted page, you can republish the page and promote it again to update the version that users can see on the target server. When you promote the page again, one previous version of the page is maintained on the server so that you can back out changes if necessary.

- 93 -

To republish and promote a page, click Administration > Site Management, right click on the page name located in the source server site tree, click Republish to. Click All to republish the page to all servers where it has previously been published, or click server name to republish to just that target server.

Figure 4.3c - 15. Republish the page

- 94 -

Figure 4.3c - 16. After the page is republished

The RiverBend page is now republished and the new version is visible only to the group of users defined as reviewers. Figure 4.3c -16 shows the republished RiverBend page with the published sign at the bottom. To update the page so that all users on the target server can view it, you must promote the republished page.

Figure 4.3c - 17. Re-promote the page

- 95 -

After promote the republished page, the page can be viewed on the target server by all users with the appropriate access rights. One previous version of the page is maintained on the target server, which becomes a version page and it can be used to back out the

changes if necessary. Version pages ( ) are no longer visible to the users and they have a visibility rule assigned, see Figure 4.3c-18.

Figure 4.3c - 18. After the page is re-promoted

Demoting your page After you promote your page on the target server, you can demote the page so that the page is no longer visible on the target server. The page returns to a published state.

To demote a page from the target server, click Administration > Site Management, right click on the promoted page and select Demote this page.

- 96 -

Figure 4.3c - 19. Demote a page

After the page is demoted, it returns to a published state. If an old version of the page with the same unique name exists, the old page becomes the promoted page again. Figure 4.3c-20 shows that the old version of RiverBend page becomes the promoted page as the same unique name exists in the target server and the newer version of the page is back in published state.

- 97 -

Figure 4.3c - 20. After the page is demoted

Disabling site management You can prevent administrative users from publishing, promoting or demoting pages using Site Management. To disable the site management functions, HTTPBasicAuthTAI should be disabled through WAS administrative console:

1. Click Security > Secure administration, applications, and infrastructure. 2. Under Authentication, expand Web security and click Trust association. 3. Uncheck Enable trust association option. 4. Save the changes and restart the server.

- 98 -

Figure 4.3c - 21. WebSphere Application Server administrative console security settings

Figure 4.3c - 22. Trust Association setting

Site management extension of the Portal Scripting Interface You can use the site management extension bean of the Portal Scripting Interface to publish, promote, or demote portal content. Please refer to WebSphere Portal Infocenter link on the Portal Scripting Interface syntax and example JACL scripts for site management: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/admin/adpsicrf_site_mngmt.html

- 99 -

4.4 Deployment topics for Themes and Skins The following section discusses deployment topics related to Portal Themes and Skins.

To establish the proper foundation, it explains the terminology and concepts for themes and skins, using the home page from the River Bend Tea and Company as an example,

It discusses how to deploy a custom theme and skin, with the emphasis on a first time deployment of this custom theme and skin.

Next, it discusses how to update a custom theme and skin, once it has already been deployed,

Finally, it discusses how to update a theme style, moving this from one server to another.

4.4.1 Introduction to Themes and Skins IBM WebSphere Portal allows the portal site's look and feel to be changed based on themes and skins. The theme controls the sites over all look and feel, while the skin determines how components, such as row or column containers and portlets, are rendered. The following graphic shows the River Bend Tea and Coffee Company's welcome page. The graphic has been annotated with red and blue arrows to differentiate items that are part of the theme, verses items that are part of the skin. These are only some of the items that are configured by themes and skins. For more in depth documentation please refer to the InfoCenter for WebSphere Portal v6.1

Figure 4.4-1: River Bend Tea & Coffee Company Welcome page

- 100 -

In the graphic, the red arrows point to items that are configured by the theme. Items such as background image, the corporate logo, the current page menu item background, menu fonts and colors, etc, are all items that that can be configured in the theme. In order to modify any of these items a theme style would need to be created or modified, or a custom theme created and applied to the page. The three blue arrows point to portlets that are displayed on the Welcome page. Portlets are displayed in containers, boxes. Skins are used to modify how those containers are displayed. For example, the Wlinks portlet at the bottom of the page has the portlet navigation drop down arrow shown, pointed to by the blue arrow. By modifying the skin, a different graphic could be used. It's important to note that themes and skins do not have a one to one relationship. This means that a given theme can use more than one skin. Conversely, a given skin can be used by more than one theme. So, for example, a theme can be applied to a set of pages and each page code use a different skin to modify how the page looks. This provides for greater re-use of themes and skins among or within a site.

Modifying an existing theme or skin, or applying theme styles and policies, allow for very comprehensive look and feel modifications for the portal site. In general, you can modify the behavior of a theme, colors, fonts, graphics, turn areas of a page on or off, and adjust settings for portions of the page such as navigation, by using theme styles or by creating a custom theme based. If additional functionality is needed in the theme that is not available in the current theme, you would need to create a new theme or modify an existing theme and deploy it. The following table shows some of the decision points that will help to determine if a full blown custom theme is needed or a theme style and policy would suffice.

- 101 -

Theme Customization

LowYesYesNoNoNoYesNoTheme Style and Policy

HighYesYesYesYesYesNoYesCustom Theme

Required effort

Turn on and off portions of page

Modify colors fonts graphics

Add or remove new elements

Change layout

Add Functionality

Created by Administrator

Created by Developer

Development of a custom theme is beyond the scope of this topic, but in the following topics, we will discuss deploying and updating a “custom” theme and skin, and applying theme styles and policies.

4.4.2 Deploying a Custom Theme and Skin Prior to WebSphere Portal v6.1, new themes and skins were deployed to the wps.war file along side out of the box themes and skins. This meant that deploying a new theme or skin, or updating an existing theme or skin, required an administrator to export the wps.war file, update the wps.war file and then deploying the updated wps.war file. This made developing and managing custom themes and skins difficult. With Websphere Portal v6.1, new themes and skins should be packaged in their own war file, or optionally ear file. Once a theme and/or skin is packaged into a war file, the file is deployed to the WebSphere_Portal application server or cluster via the WebSphere admin console or via script just like any other Enterprise Application. The Portal is then made aware of the new theme or skin and it's associated context root. After Portal is made aware of the new theme or skin, users or administrators can apply the theme or skin to portal pages. When updating an existing custom theme, i.e. one that is not packaged in

- 102 -

wps.war, all that is needed is for the updated war file to be deployed as an update via the WebSphere administration console. The steps to create a new theme are beyond the scope of this topic. They are documented in the WebSphere Portal v6.1 InfoCenter. Refer to the references section at the end of this topic for a link to the article in the InfoCenter. 1

Scenario: Deploying a new theme and skin The design team has developed a new theme, called RiverBendTheme, by modifying a copy of the IBM theme that ships with WebSphere Portal v6.1. They would like the package deployed to the development server for testing and continued development. The team has also included a new skin, based on the IBM skin, called RiverBendSkin. For ease of deployment, the theme and skin are packaged in the riverbendtheme.war file. The context root to be used for the war file will be /riverbend. The steps to deploy a war file containing the new theme, RiverBendTheme, and the new skin, RiverBendSkin, follow. They are broken up into 2 sets of steps, one for the WebSphere Administrator and one for the Portal Administrator. Task: Deploy the riverbendtheme.war to the WebSphere Portal development cluster Role: WebSphere Administrator

Note: These steps assume the war file has been transfered to c:\temp on the development server and that deployment is being done from the development server

1. Access the WebSphere administration console from a web browser

http://localhost:10041/admin 2. Login with a user-id and password that has administration access to WebSphere

User: wasadmin Password: wasadmin

3. Click the + next to Applications to expand the Applications navigation menu 4. Click Install New Application 5. On the “Preparing for the application installation” page do the following:

1. Under “Path to the new application” select “Local file system” 2. In the text box labeled “Full path” either type the full path to the

riverbendtheme.war file or use the browse button to locate the file. c:\temp\riverbentheme.war

3. In the “Context root” text box enter /riverbend 4. Click Next

1 References used in this section include:"Creating a new theme" http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/dev/dgn_crthm.html

- 103 -

Figure 4.4a-1- Select war file and enter the Context root

6. On the “Select installation options” page do the following:

1. In the “Application name” text box modify the text to be River Bend Theme and Skin

2. Click Next

- 104 -

Figure 4.4a-2 - Set Application name

7. On the “Map modules to server” page do the following: 1. Place a check mark in the “Select” box next to the RiverBendThemAndSkin

module 2. In the “Clusters and Servers” list box highlight the application server(s) and

web servers to deploy the application to. Note: In our demo environment we used the WebSphere_Portal server. Note: To select more than on item in the list box hold down the shift key

3. Click Apply 4. Verify that the Module is now mapped to the correct servers in the “Server”

field 5. Click Next

- 105 -

Figure 4.4a-3 - Map modules to servers

8. On the “Map virtual hosts for Web modules” page do the following

1. In the “Virtual host” drop down select the correct virtual host for the Web module Note: In our demo environment we used the default virtual host default_host

2. Click Next

Figure 4.4a-4 - Map virtual hosts for Web modules

9. On the “Summary” page, click Finish 10. On the “Installing” page click Save 11. Start the River Bend Theme and Skin application by doing the following:

1. From the WebSphere administration console click the + next to Applications to expand the Applications navigation menu

2. Click on Enterprise Applications 3. Scroll down to the River Bend Theme and Skin application

- 106 -

4. Place a check mark in the “Select” column next to the application 5. Click Start to start the application

Task: Register the new theme and skin with WebSphere Portal Role: WebSphere Portal Administrator

Note: You can use the Themes and Skins administration page of WebSphere Portal to register a new theme but you cannot specify the context root of the theme or skin there at this time. So, we will use xmlaccess scripts to register the new theme and skin. We will modify the sample script provided by WebSphere Portal called DeployThemeFromWebModule.xml to suit our purpose.

1. Copy PortalServer/doc/xml-samples/DeployThemeFromWebModule.xml to

c:\temp\deployriverbendthemeandskin.xml 2. Edit c:\temp\deployriverbendthemeandskin.xml to match the following. Changes

are in red.

<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_6.1.0.xsd" type="update" create-oids="true"> <portal action="locate"> <!-- Sample for deploying themes and skins in an XML script. Note that this only created the database entries; you still need to provide the rendering JSPs by deploying the corresponding web module under the specified context root in the application server. --> <skin action="update" active="true" objectid="riverbendskin" uniquename="ibm.portal.skin.riverbend" resourceroot="RiverBendSkin" context-root="/riverbend"> <localedata locale="en"> <title>River Bend Skin</title> <description>A skin for River Bend</description> </localedata> </skin> <theme action="update" active="true" defaultskinref="riverbendskin" uniquename= "ibm.portal.theme.riverbend" resourceroot="RiverBendTheme" context-root="/riverbend"> <localedata locale="en"> <title>River Bend Theme</title> </localedata> <!-- There's only one skin that may be combined with this theme. --> <allowed-skin skin="riverbendskin" update="set"/> </theme> </portal> </request>

3. From a command prompt change to the PortalServer/bin directory

- 107 -

4. Run the following to execute the xmlaccess script and register the theme and skin 1. xmlaccess.bat -user wpsadmin -password odwnwpsadm -url

localhost/wps/config -in c:\temp\deployriverbendthemeandskim.xml -out c:\temp\deployriverbendthemeandskin.out

5. Optional: Verify that you can see the theme and skin from the Portal administration Themes and Skins page by doing the following: 1. Login into WebSphere Portal with an administration id 2. Click Administration 3. Click Themes and Skins 4. Look for the River Bend Theme in the list of available themes. 5. Look for the River Bend Skin in the list of available skins

Figure 4.4a-5 - Verify theme and skin availability

4.4.3 Updating a Custom Theme and Skin Once a custom theme or skin is deployed, it is inevitable that changes will need to be made and the modifications deployed for use. Updating a theme or skin that has been developed and deployed as it's own war or ear file follows the same process used to update a Web Application via the WebSphere Administration console.

Scenario: Updating a custom theme and skin After deploying the initial River Bend theme and skin, which was based on the out of the box IBM theme and skin, and only contained a few minor modifications, the design team has now made further modifications to the theme and skin. They have requested that the modifications, stored in the riverbendtheme.war file, be deployed to the development server for further testing. Since the theme and skin have already been deployed and

- 108 -

registered with Portal using the /riverbend context root, the current Web application will be updated with the new war and keep the existing context root so no changes are needed in Portal. The steps to deploy the updated war file follow. Only the WebSphere Administrator will be involved in the process as the theme and skin have already been registered with Portal using the context root /riverbend and that will continue to be used after the update. Task: Update the riverbendtheme.war via the WebSphere Administation console Role: WebSphere Administrator

Note: These steps assume the war file has been transfered to c:\temp on the development server and that deployment is being done from the development server

1. Access the WebSphere administration console from a web browser

http://localhost:10041/admin 2. Login with a user-id and password that has administration access to WebSphere

User: wasadmin Password: wasadmin

3. Click the + next to Applications to expand the Applications navigation menu 4. Click Enterprise Applications 5. Scroll down and locate the River Bend Theme and Skin application

Note: You may need to go to additional pages to locate the application. They are sorted alphabetically with uppercase first by default.

6. Place a check mark in the select column next to the application

Figure 4.4b-1- select the application to update

7. Click the Update button at the top of the page to start the update process

Figure 4.4b-2 – start the update process 8. On the “Preparing for the application installation” page do the following:

1. Select Replace the entire application 2. Select Local file system under “Specify the path to the replacement ear

- 109 -

file” 3. In the text box labeled “Full path” either type the full path to the

riverbendtheme.war file or use the browse button to locate the file. c:\temp\riverbentheme.war

4. In the “Context root” text box enter /riverbend 5. Click Next

Figure 4.4b-3 – Select war file and enter the context root

9. On the “Select installation options” page click Next

- 110 -

Figure 4.4b-4 – Select installation options

10. On the “Map modules to server” page do the following: 1. Verify that the update is being deployed to the WebSphere Portal server 2. Click Next

- 111 -

Figure 4.4b-5 – Map modules to servers

11. On the “Summary” page, click Finish 12. On the “Installing” page click Save to save the changes to the WebSphere

configuration Note: Once the changes have been saved and synchronized to the node they will be used on pages that use the custom theme or skin.

4.4.4 - Deploying Theme Styles As mentioned earlier, when no additional functionality is required, or changes to page layout or new elements are needed in the theme, generally a new theme policy and/or style will be sufficient to modify the appearance of your site. A theme style and policy can be used to “select colors, fonts, graphics, turn areas of the page on and off, and adjust the settings for areas of the page such as the navigation.” The theme policy is used to turn portions of the page on or off and adjust settings of those areas that are rendered, such as control the menu bread crumbs. These elements are controlled by modifying policy attributes and applying the policy to one or more pages. While not all out of the box themes will support all policy attributes, you can find the list of attributes in the Info Center. The theme style is used to modify the colors, fonts, and graphics displayed by the theme.

The following section discusses theme styles and policies and provides a specific example of how to move a theme style from one environment to another. 2

2 References for this section include: “Policy Attributes” http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/dev/dgn_themes.html “Customizing themes using theme styles” http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/topic/com.ibm.wp.ent.doc/design/ThemeCustomizerHelp_ovw.html

- 112 -

Theme Style versus Theme Policy There are a few differences between Theme Style and Theme Policy. They are as follows:

Theme Style

Creation: You create a new Theme Style using the Portal Administration, under Portal User Interface > Theme Customizer.

Edition:

You can edit a Theme Style using the Theme Customizer.

Deletion: You can remove a Theme Style using the Theme Customizer.

Applying to pages:

You can apply a Theme Style to a page using the Theme Customizer or the Manage Pages portlet. The Manage Pages portlet treats a Theme Style as a Theme Policy.

Theme Policy

Creation: You create a new Theme Policy using the XML Configuration Interface.

Edition:

You can not edit a Theme Policy using the Theme Customizer. You can update a Theme Policy using the XML Configuration Interface (xmlaccess).

Deletion:

You can not delete a Theme Policy using the Theme Customizer. You can remove a Theme Policy using the XML Configuration Interface (xmlaccess).

Applying to pages:

You can apply a Theme Policy to a page using the Manage Pages portlet or the XML Configuration Interface. The process to transfer both artifacts from one server to the other is the same.

- 113 -

Scenario: Moving a theme style from one server to another In order to transfer a Theme Style from one server to another, you have to follow the same procedure to export and import a Theme Policy using the XML Configuration Interface. A Theme Style can be treated as a Theme Policy. Alternatively, a Theme Policy can not be treated as a Theme Style. In our scenario, we have created a new Theme Style on the development machine and transferred it to our staging server. This is described in the steps below.

Export the Theme Style from the development machine

1. Create an XML file that will be used to export your Theme Style. In this example, we will export the Theme Style “RiverBendStyle”, and the exportRiverBendStyle.xml will be used for that:

exportRiverBendStyle.xml <?xml version="1.0" encoding="UTF-8"?> <request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd" create-oids="true" type="export" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <portal action="locate"> <policy-node action="export" label="WebPage" type="theme" path="RiverBendStyle"> <url>file:///c:/temp/RiverBendStyle.xml</url> </policy-node> </portal> </request>

2. Copy the exportRiverBendStyle.xml to <PortalServer>/bin directory 3. Use the XML configuration interface, xmlaccess.bat script, in order to export the

Theme Style. The command below will generate a file called RiverBendStyle.xml under the C:\temp directory:

<PortalServer>/bin/xmlaccess.bat –in exportRiverBendStyle.xml –url http://<development>:10040/wps/config -user wasadmin -pwd <password>

4. The theme file has been exported successfully if the following message is

displayed: <status element=”all” result=”ok”/>.

Example:

- 114 -

5. The Theme Style will be exported into the file RiverBendStyle.xml under C:\temp directory. This file represents the Theme Style XML definition

6. Copy the generated file RiverBendStyle.xml to the target machine

Import the Theme Style to the staging machine

1. Copy the generated file RiverBendStyle.xml to the <PortalServer>/bin directory. 2. Create an XML file that will be used to import your Theme Style.

importRiverBendStyle.xml <?xml version="1.0" encoding="UTF-8"?> <request xsi:noNamespaceSchemaLocation="PortalConfig_1.4.xsd" create-oids="true" type="update" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <portal action="locate"> <policy-node action="update" label="WebPage" type="" path=""> <url>file:///c:/WebSphere/PortalServer/bin/RiverBendStyle.xml </url> </policy-node> </portal> </request>

3. Copy the importRiverBendStyle.xml to the <PortalServer>/bin directory

<PortalServer>/bin/xmlaccess.bat –in importRiverBendStyle.xml –url http://<development>:10040/wps/config -user wasadmin -pwd <password>

4. The theme file has been imported successfully if the following message is displayed:

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

- 115 -

Example:

5. Your new Theme Style will appear in the list of available Theme Styles:

Note: You can use the same procedure to transfer a Theme Style from staging to production. When you have a clustered environment, you can choose one of the cluster

- 116 -

members to be the target server. As this is a change made at a database level, you only have to do it once.

- 117 -

Topic 5. Syndication and how to use it

Objective of this section In this section, we describe a specific Syndication example as it applies to the RiverBend Tea and Coffee company Portal v. 6.1 environment.

5.1 Syndication In this scenario, we will show you how to move the WCM data from a development machine to a staging machine. The same process can be used to transfer WCM contents from the Staging environment to the Production environment. If you need more details about how Syndication works, take a look at the following link: http://www-10.lotus.com/ldd/portalwiki.nsf/dx/5.1.2-syndication

5.2 Syndication Example In this section we describe in detail the steps we took to complete syndication of the RiverBend library from the WCM instance on wps01.itso.ibm.com (Syndicator) to the WCM instance on wps02.itso.ibm.com (Subscriber). From here onwards we will refer to these environments as the Syndicator and Subscriber. To ensure both the Syndicator WCM instance and Subscriber WCM instance were at the same WCM version we looked at the information available in the following file on both the servers – C:\IBM\WebSphere\wp_profile\PortalServer\log\VersionInfo.log.

wps01.itso.ibm.com (Syndicator)

------------------------------------------------------------ IBM WebSphere Portal 6.1 Build Level: wp610_493_01 (2008-06-18 17:24) Server Name: WebSphere_Portal Started at: 11/6/2008 10:43:47:953 EST Installed FixPacks: None Installed Interim Fixes: None

- 118 -

wps02.itso.ibm.com (Subscriber)

------------------------------------------------------------ IBM WebSphere Portal 6.1 Build Level: wp610_493_01 (2008-06-18 17:24) Server Name: WebSphere_Portal Started at: 11/6/2008 10:34:46:281 EST Installed FixPacks: None Installed Interim Fixes: None

Next we check network connectivity between the two servers to ensure both the servers are available on the network.

The screenshots provided below illustrates the results of the ping command between the two servers.

Figure 5-1: Check network connectivity from the Syndicator to the Subscriber

- 119 -

Figure 5-2: Check network connectivity from the Subscriber to the Syndicator

Things to remember when doing first time syndication: First-time syndication to an existing library is not supported. Attempting to

syndicate a library to a subscriber that already has a library with the same name will result in an exception. Hence it is recommended not to use the default Web Content library. Although the libraries have the same name, they have different UUIDs.

Access control settings are not part of syndication, and hence you must manually

set access permissions on the subscriber's library when syndicating for the first time. If the library does not exist on the subscriber, it will be created during syndication. By default, no access control settings are specified on the new library, so you must set them manually before users can access content in the new library. It is not required that the settings on the subscriber's library match those on the Syndicators library, because you might want to provide different access for users on the subscribing server.

Starting the Syndication configuration Log in to the Portal administration portlet as the administrator and access the Web Content Libraries portlet to ensure the list of WCM libraries are available to both WCM instances. To verify this, use two browser instances. The screenshots below illustrates this.

- 120 -

Web Content Libraries on the Syndicator The Syndicator has 2 libraries created. One called Web Content, which is the default library, and the “RiverBendLib” library, which is the one we are using in this scenario, as shown in the screenshot below:

Figure 5-3: Web Content Libraries available on the Syndicator

Web Content Libraries on the Subscriber The Subscriber has the default Web Content library as shown in the screenshot below. The syndicated library, RiverBendLib, will be automatically created during the Syndication process. So, do NOT create this library in the Subscriber machine.

Figure 5-4: Web Content Libraries available on the Subscriber

- 121 -

Configuring Syndication On the Syndicator administration portlet click on the Syndicator link available in the left hand navigator. The screenshot below illustrates the Syndicator view which at this stage does not contain any syndicator entries.

Figure 5-5: Web Content Syndicators View

On the Subscriber administration portlet click on the Subscriber link available in the left hand navigator. The screenshot below illustrates the Subscriber view which at this stage does not contain any subscriber entries.

Figure 5-6: Web Content Subscribers View

Tip: To create a new Syndicator and Subscriber entry at the same time we recommend using two separate browser instances next to each other.

Creating a new Syndicator configuration

Use the Create New Syndicator action to create a new Syndicator configuration. The screenshot below illustrates the page that loads up.

- 122 -

Figure 5-7: Create New Syndicator

Enter suitable values in the following fields – Name: Enter a name for this syndicator configuration entry. Description: Enter a description. Enabled checkbox: Ensure that this checkbox is checked to enable this

syndicator configuration entry.

Before entering the information about the Subscriber server, keep this browser as it is and open a new one to access the Subscriber machine.

Creating a new Subscriber configuration

Use the Create New Subscriber action to create a new Subscriber configuration. The screenshot below illustrates the page that loads up.

- 123 -

Figure 5-8: Create New Subscriber

Enter suitable values in the following fields – Name: Enter a name for this subscriber configuration entry. Description: Enter a description. Syndicator Name: Enter the value from the Name field in the syndicator

configuration entry as seen in Figure 5-8 above, but this field can be any name, it doesn’t have to match.

Syndicator ID: Enter the value from the Subscriber ID field in the syndicator configuration entry as seen in Figure 5-8 above, this field must match.

Syndicator URL: Enter the value from the Subscriber URL field in the syndicator configuration entry as seen in Figure 5-8 above.

Enabled checkbox: Ensure that this checkbox is checked to enable this subscriber configuration entry. To disable this subscriber configuration entry, deselect this checkbox.

Now, go back to the Syndicator configuration and complete it with the Subscriber information:

- 124 -

Figure 5-9: Create New Syndicator

Subscriber Name: Enter the value from the Name field in the subscriber configuration entry as seen in Figure 8 above, but this field can be any name, it doesn’t have to match.

Subscriber ID: Enter the value from the Subscriber ID field in the subscriber configuration entry as seen in Figure 8 above, this field must match.

Subscriber URL: Enter the value from the Subscriber URL field in the subscriber configuration entry as seen in Figure 8 above.

Enabled checkbox: Ensure that this checkbox is checked to enable this syndicator configuration entry. To disable this syndicator configuration entry, deselect this checkbox.

Click on Add libraries

Use this action to add WCM libraries that should be syndicated as part of this syndicator configuration entry. This action loads the portlet illustrated in the screenshot below which allows you to add the WCM libraries to be included as part of this syndicator configuration. In this case we selected the RiverBendLib library with All Items as the scope.

- 125 -

Scope All Items will syndicate all items. Scope Live Items will only syndicate items that are in the published state.

Figure 5-10: Web Content Syndicators – Add Libraries

Once the syndicator configuration and subscriber configuration field values have been correctly entered, saved the syndicator entry first by using the OK action available. The screenshot below illustrates the syndicator view which now reflects the new syndication entry. Notice the Status and Last Update column values.

Figure 5-11: Web Content Syndicators View - Status Idle

After the syndicator entry is saved, click the OK action on the subscriber configuration entry to save the subscriber configuration entry. The screenshot below illustrates the subscriber view which now reflects the new syndication entry. Notice the Status and Last Update column values.

- 126 -

Figure 5-12: Web Content Subscribers View - Status Idle

Click on Rebuild Syndication to start the Syndication for the first time as illustrated in the screenshot below:

Figure 5-13: The Rebuild Syndication button

Once the syndication process has completed, the Syndicator and Subscriber views display the idle status as illustrated in the screenshots below.

Figure 14: Web Content Subscribers View – Status Idle

- 127 -

Figure 15: Web Content Syndicators View – Status Idle

Monitor the Syndicator/Subscriber Status Report We used the Last Update column entry links on the syndicator and subscriber to review the Syndicator and Subscriber status reports as illustrated in the screenshots provided below.

- 128 -

Figure 5-16: Syndicator Status Report

When the first Syndication is done, the library “RiverBendLib” has been automativally created and populated in the Subscriber machine. You will have to give the same access rights you have set in the Syndicator for this library. The Syndication process will not syndicate the library access permissions. You will set the permissions to this library using the Set permissions ( ) button and the Library resources button ( ).

- 129 -

- 130 -

Topic 6. Maintenance and quickfixes

6.1 Objective The following section provides an overview of the Portal product maintenance strategy and how it applies to a Portal Infrastructure which includes several different Portal environments from development through to production. This section also includes some consideration for the application of both emergency Portal product Interim Fixes and urgent customer application fixes.

6.2 Product Maintenance Overview Even though IBM WebSphere Portal developers strive to make available only the highest quality software to our customers, there are situations where problems are identified which require a corrective service update to resolve. Corrective service updates are delivered via several different Maintenance Delivery Vehicles (MDVs) ranging from the most granular to the most comprehensive. Application of corrective service to existing installed software is called maintenance. The list of MDVs includes: Fixes Interim Fixes and Test Fixes

Interim Fixes (iFixes) usually fix a single problem identified by an Authorized Program Analysis Report (APAR). Application of this type of fix is usually only recommended when the problem symptoms are experienced by the customer and if the fix is not available in one of the other MDVs. In the rare case when a fix is developed specifically for a problem seen on your system, you may be asked to install a test fix and provide feedback to the fix developers. PK67104 is an example of a typically named APAR that addresses a specific problem.

Cumulative Fixes

Cumulative Fixes include a number of fixes for one particular functional area such as the Web Content Management (WCM) component. APARs are also used to identify cumulative fixes. PK73933 is an example of a Cumulative Fix APAR.

Fix Packs This is the standard delivery vehicle for Portal product updates. Fix Packs are a cumulative roll-up of fixes up to a certain point in time. Application of Fix Packs result in all previously applied Interim Fixes being uninstalled, and so care must be taken to reinstall Interim Fixes if required. Fix Packs are named as incremental numbers starting at 1 for a particular Refresh Pack level. For

- 131 -

example once the Fix Pack 1 is applied to a Portal environment, the Fix Pack number is represented in the fourth numeric position in the numbering scheme: 6.1.0.1.

Refresh Packs

This is a cumulative roll-up of fixes including feature enhancements. Refresh Packs supersede all prior Fixes and Fix Packs for a specific release of the product. Application of Refresh Packs result in all previously applied Fix Packs and Interim Fixes being uninstalled, and so care must be taken to reinstall them if required. An alternate form of a Refresh Pack may also be made available from time to time. A Manufacturing Refresh is new installation media (electronic or physical) that would include the 6.1.0.0 version of the product along with a particular Refresh Pack already applied. Refresh Packs are named as incremental numbers starting at 1 for a particular Portal Version. For example once Refresh Pack 1 is applied to a Portal environment, the Refresh Pack number is represented in the third numeric position in the numbering scheme: 6.1.1.0.

It is strongly recommended that critical functions of your custom applications be regression tested when a new Fix Pack or Refresh Pack is applied. In the case where an Interim Fix, Test Fix, or Cumulative Fix is applied, we recommend that you test functions affected by the fixed component. Further details on this topic are available online in the document: IBM - Update Strategy for WebSphere Portal versions 6.0 and 6.1 http://www-01.ibm.com/support/docview.wss?uid=swg21248245

6.3 Maintenance Download Information IBM maintains a list of current recommended fixes for each of the different supported versions of WebSphere Portal on our web page. This page includes links to download the latest recommended Fix Pack, Cumulative Fixes and important Interim Fixes that can be applied on top of the latest recommended Fix Pack. It is also possible to find links to download older superseded fix packs and refresh packs, at the bottom of each version table. An example for this is as follows: From our Recommended fixes and updates for WebSphere Portal and Web Content Management page at: http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg27007603, if you click on PK73933 which is the current recommended WCM cumulative fix, you will be prompted to log in to the fixcentral site.

- 132 -

Note: A recent change has been made to the way IBM distributes WebSphere Portal maintenance. WebSphere Portal product fixes are now stored on the IBM Fix Central repository. When you select one of the fixes from the recommended fixes page, you will be redirected to the fix central site: http://www.ibm.com/support/fixcentral. Once logged in, the next screen seen is the beginning of the packaging of the fix from the fix central site:

This automatically refreshes to show the select fixes and download method screen:

To proceed with the fix download, you’ll need to do the following:

1) Select the fix and preferred download method 2) Click Continue. 3) On the next screen, read and Accept the terms and conditions by clicking on I

Agree

- 133 -

Note that in this example, PK73933’s entire prerequisite chain appears in this screen, including updates to WebSphere Application Server that are also prerequisites. This feature greatly simplifies the process of obtaining fixes for WebSphere Portal.

Note: In a subsequent section, we explain how to use the Portal Update Installer (PUI) to provide a comprehensive listing of fixes which have already been installed to the existing Portal environment.

4) On the next screen, you have the option of deselecting any of the included prerequisites in the event you already have them downloaded or installed.

- 134 -

5) Click Download Now

.

6.3.a Downloading Portlet Updates The process of downloading updates to Portlets is different from the process used to download updates to the WebSphere Portal Product. Updates to many of the Portlets shipped with the WebSphere Product, can be found on the WebSphere Portal Business Solutions catalog, found on-line at: http://catalog.lotus.com/wps/portal/portal To determine if an update exists for a Portlet you have installed, search for the portlet’s name on the catalog’s main page, as shown in the figure below.

- 135 -

To view the update date, mouse over the Info Icon for the portlet on the search results page.

Click on the Portlet name to go to the portlet’s individual page and from there you can click the download link to download the updated portlet. Note: In a subsequent section (6.4.c), we describe the process for installing updated portlets

6.4 Managing Maintenance installation The advantages of keeping your installed Portal software at a current maintenance level are many. Foremost is the reduced risk of encountering a problem that has already been discovered and fixed in a later services release. You can also take advantage of performance, stability and functional enhancements already incorporated in the software. An optimal Portal infrastructure will consist of a staging environment that is essentially a duplicate copy of the production environment available for in-house quality assurance (QA) testing. In order to ensure this consistency between environments, as many components as possible should be the same between the staging and production server, including the hardware (storage devices, network connectivity, memory, and CPU), as well as the versions and fix levels of all the software components: operating system application server, webserver, database, security servers, and any others you have in your environment. If your production environment runs on a cluster of Windows servers, then the staging environment should be the same. It is recommended that thorough testing of any maintenance patch be done first on the staging server to ensure it does not introduce any problems or unexpected results.

- 136 -

Before being applied to the production environment, it is a good idea to become familiar with the steps required to perform the update to prevent problems on the production site. For practice, the update can be de-installed and reinstalled several times on the staging environment or other testing system if one is available. Important: It is critical to carefully maintain a list of installed fixes and fixpacks you have installed on each of your machines. It is good practice to keep backup copies of all the fixes that have been applied on a different machine from your Portal server.

6.4.a Portal Update Installer As was the case in earlier Portal releases, the Portal Update Installer (PUI) is the tool used to apply WebSphere Portal maintenance. The link to the Portal 6.1 specific Update Installer tool is on the recommended fixes page mentioned above, and can also be accessed directly from the URL below: IBM - WebSphere Portal Update Installer http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg24006942#6.1 With Portal 6.1, you have a choice to use either a platform specific version of the tool or a universal update installer. The platform specific tools include a Java™ runtime environment so that you are able to invoke the graphical "Wizard" interface without setting the necessary environment variables first as is required with the universal update installer. Instructions for how to use the IBM WebSphere Portal Update Installer command line and graphical Wizard to apply updates are included in the README that comes with the Portal Update Installer package in the doc folder.

6.4.b How to determine if an interim fix needs to be reinstalled after application of an Fix Pack or Refresh Pack. Before you apply a Fix Pack or Refresh Pack to your Portal server, use the PUI to obtain a list of fixes you currently have installed. The PUI is the recommended method of viewing the list of installed Portal Fixes, although it is possible to view the event.history file in the directory <WP_root>/version/ to extract what has been installed. The syntax to show the list of fixes on the test server used for this project is as follows:

C:\IBM\WebSphere\PortalServer\update> updatePortal -fix -installDir "C:\IBM\WebSphere\PortalServer"

The syntax to show the list of installed fix packs on the test server would be:

- 137 -

C:\IBM\WebSphere\PortalServer\update> updatePortal -fixpack -installDir "C:\IBM\WebSphere\PortalServer"

For every Interim Fix included in the resulting list, you must determine if that fix is included in Fix Pack or Refresh Pack that you are applying. You can do this by searching the Fix list for WebSphere Portal Version 6.1 at: http://www-01.ibm.com/support/docview.wss?rs=688&uid=swg27008899 If the fix is not in the Fix Pack or Refresh Pack, then you will need to confirm that the copy of the fix you have can be applied again on top of the Fix Pack or Refresh Pack you are installing. Often, the README for the fix will show what service levels of WebSphere Portal this fix can be applied on top of. If your Pack or Refresh Pack is not in the README, then consult the fix web page. If you are still unable to determine if a newer version of the fix is available, then check with IBM support to determine if a newer version of the fix is available.

6.4.c Installing Portlet Updates This section shows how to install updates to Portlets. For updates to Portlets downloaded from the Portlet Catalog, if there are special instructions for installing the Portlet, the special instructions may be included in the downloaded zip package or in the 'Support' section of the portlet's catalog entry in the WebSphere Portal Catalog, as shown in the following figure:

If there are no special installation instructions in the Deployment and Installation section of the Sales and Support page, then the default portlet update instructions can be followed. These are the same instructions that would be used if your portal developer

- 138 -

updated a portlet through RAD or other IDE to make the changes to the java source file and then provided you with a new portlet war file, containing the update. The default method of applying an update to a porlet is to use the Portal Administration portlet: Administration > portlet management > web modules > and search for the portlet’s web module that you want to update. Once you find the web module that you

want to update, click on the web module’s update button: to apply the update. An example for this is as follows: In our example, we demonstrate applying an update to the GoogleGadget Portlet.

1. Find the web module for the GoogleGadget Portlet the in the Portal Administration portlet: Administration > portlet management > web modules and click on it’s update button as can be seen in the following figure:

2. On the next screen, browse to the location of the updated war file and click Next:

3. In the following step, you have the opportunity to change some of the Portlet’s configuration before clicking Next:

- 139 -

4. If the web module update is successful, you should see the success message as shown in the following figure:

There is further information available on this topic in the InfoCenter article “Updating Web modules, portlet applications, and portlets”: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/topic/com.ibm.wp.ent.doc/admin/portletapps_update.html

6.4.d Applying Portal Maintenance updates in a clustered environment In a production environment, applying portal maintenance to a cluster of portal servers typically involves applying the update to each node in the cluster, one at a time. If possible, apply maintenance during one of the least busy times of the day or week. If it is possible for only half of the servers in your cluster to carry the lighter than normal load during the off peak time, then to maintain 24x7 availability, then leave half of the nodes running and stop the node agents and Portal servers on the other half. The node you choose to install the fix on first is arbitrary. After applying the maintenance to the

- 140 -

stopped nodes, bring them back online and repeat the process for the other nodes in the cluster. If there are special instructions to apply a particular fix pack and interim fix to a cluster, the instructions are provided with the corrective service package. If a portal update also requires an update to the underlying WebSphere Application Server, then it is important to note that the update must be applied to the Deployment Manager of the cell before the other participant nodes. If the corrective service updates a previously deployed enterprise application, then you will be instructed to disable deployment manager auto-synchronization while the fix is being applied to all the nodes in the cluster. If the portal update requires an update to the underlying WebSphere Portal databases or other supporting software such as databases servers, then refer to the specific instructions provided with the update. The WebSphere Portal InfoCenter contains additional information on applying maintenance to a Portal Cluster at: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp?topic=/com.ibm.wp.ent.doc/plan/clus_maint.html

6.5 What to do when Portal product updates are needed for a solution release move If you are planning to move your portal release to a new environment, you will need to ensure that the portal server you are moving to is at the same update level as the one you are moving from. Updates must be applied to the target portal server environment in the same manner that they were applied to the source server environment. There is no facility to move updates from one server to another; instead each server (the source server and the target server) must be dealt with independently.

6.6 Emergency fix “fastpath” Situations One of the main goals of this book is to describe how to move changes through a Portal environment that is made up of several different stages along the way from development and test, through staging to production. There are various reasons changes need to be made to a working portal system. Creating an entirely new portal solution release that includes new functionality and may also require some new complementary product software be installed, can be a very large undertaking. As described in section 3.1 Portal Environment configurations, after the components are created in the development environment, they are moved over to QA where they are integrated and tested initially. The release moves from QA on to the user acceptance testing (UAT) environment and then over to staging for extensive performance testing, before finally being moved over to the production servers. It is important to carefully tag and version every component along the way as well as document the results and effects of any changes made to the portal release or the portal

- 141 -

environment it is running in. In most organizations, this is an ongoing process that takes time for a release to move from one end of the chain to the other. There may be cases where a critical update, either to the Portal product itself via one of the above mentioned maintenance delivery vehicles, or an urgent fix to part of the release that was developed by you, needs to be fast-tracked through the pipeline of environments to the production server. The figure below illustrates this concept of how an emergency fast-path fix to production would by-pass the traditional staged approach of applying updates through the environment.

Build Release Cycle

PortalDeveloper

DevelopmentServer

BuildServer

SourceCode

Repository

DevelopmentBuild

StagingServer

ProductionServer

DevelopmentIntegration

Test

User AcceptanceTest & QA

Release

ContentCreator

BuildMaster

CODE

SCRIPTS

CONTENT

Emergency Fix to production

In an optimal world, these changes would never need to be made. However, to mitigate the impact that an event of this type will have in your organization, it’s best to have a plan in place to deal with application of fixes that are urgently needed in production.

- 142 -

Unless you maintain a duplicate pipeline of servers available for this purpose, then the normal flow of a release deployment will need to be interrupted for the processing of the higher priority emergency fix. The actual steps that need to be taken to deploy the emergency fix will vary depending on the number of components affected by the emergency fix that needs to be made and the resources available to test the emergency fix as well as the state of the staging server where the changes need to be tested. At a minimum, you may need to make the emergency fix testing take priority over the test of the next release already in progress. At a maximum, you may need to consider rolling-back changes made to a staging server if a differential release is deployed on it for testing that has not yet reached the production server environment. Whatever situation you are in, the site’s downtime can be positively impacted if this situation is anticipated and planned for.

- 143 -

Topic 7. Backup and Restore procedures

Objective of this section The following section discusses best practices and specific methods to follow when performing back up and restore procedures.

Production backup procedures The backup and recovery of WebSphere Portal v6.1 is a complex task if you do not understand what to backup. This section explores the issues and procedures on how to successfully create a backup of your portal V6.1 environment.

-Why-What-How-When

BackupsProcedure

After reading this section, you should be able to:

• Describe the reasons for creating backups. • Identify the components that need to be backed up in order to restore a given

portal configuration. • Understand the steps necessary to backup your WebSphere Portal Server

environment, • Implement a backup schedule that meets your availability requirements, • Determine if the XML script tool (XML Access) should be used as part of the

backup plan.

Key reasons for having a well defined backup strategy: The following reasons are some of the main reasons your organization should have a well defined and tested back-up strategy:

• Having a backup policy is mandatory under most corporate availability policies. • Backups will reduce your cost of operation and increase the rate of return of your

investment in Information Technologies. Recovering from a catastrophic failure can be a very expensive transaction.

• Backups will minimize your operation risk. Upgrades and code deployments will present less technical risk as the environment can be recovered if anything fails or break during the change window.

- 144 -

At minimum you will want to backup the WebSphere directories including the Application server, wp_profile and Portal server sub-directories. It is also recommended to take a backup of the portal databases in conjunction with the file system backups.

The overall strategy is to stop a group of portal nodes then take a file system backup of those stopped nodes, restart those nodes and do the same until all nodes have been backed up. Later stop the deployment manager, take the file system backup of the deployment manager directories and finally take the database and optional backups.

Backups are recommended before any major change to the environment, for example before applying fixes and patches to middleware software. Also backing up before a major code release will minimize the risk of introducing unrecoverable points of failure to the environment. Most companies will also have a periodic backup policy for disaster recovery reasons. Those policies range from weekly to monthly to quarterly. In most cases daily database backups are also in place.

- 145 -

Backup Overview:

Start Backup

24X7Backup ?

Stop1/2

Nodes

TakeFile System

BackupStopped Nodes

StartStoppedNodes

StopAll

Nodes

All NodesBackup?

Cluster?

StopDMGR

TakeDMGR

File SystemBackup

TakeOptionalBackups

StartDMGR

End Backup

TakePortal DBBackups

True

True

True

False False

False

Backup Procedure

The list below show the main tasks needed for backing up a portal production site while maintaining a 24X7 operation. This backup procedure consist of stopping a fraction of the nodes on the cluster and then taking a file system backup of the Application Server and Portal root directories while the Portal and node agents are stopped. The remaining nodes on the cluster continue to operate and maintain the 24X7 availability of the site. This process is repeated until a file system backup is taken for all of the nodes and the Deployment Manager on the cluster.

For a 24X7 operation we recommend the following:

1. The portal and application databases must be configured for online backups. Please see your Database product documentation.

2. Your cluster must have at least two nodes so one node can handle your site load while the other node is backed up..

It is considered a good practice to take backups of the portal databases during the same backup maintenance window. Use your database backup tools to do online backups of the following databases:

-COMMUN, CUSTOM, FDBKDB,JCRDB,LMDB and RELEASE portal databases.

- 146 -

The general outline of the backup procedure is:

1. Stop a group of Portal nodes in the cluster. 2. Take a file system backup of the stopped nodes. 3. Start the stopped nodes. 4. Stop another group of Portal nodes in the cluster. 5. Take a file system backup of the stopped nodes. 6. Start the stopped nodes. 7. Repeat until all the nodes have been stopped and file system backups are taken of

each node. 8. Stop the deployment manager 9. Take a file system backup of the Deployment Manager node. 10. Take a backup of the portal databases. 11. Optional – backup LDAP and HTTP Server directories. 12. Restart Deployment Manager.

River Bend Backup Test Case:

River Bend Environments

PRODUCTION

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

STAGING

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

DEVELOPMENT

Database LDAP

WebSphere Portal

Firewall

WebSphereApplication Server

River Bend Environments

PRODUCTION

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

STAGING

Database LDAP

WebSphere Portal

WebSphere Portal

Firewall

WebSphere ApplicationServer Deployment Manager

DEVELOPMENT

Database LDAP

WebSphere Portal

Firewall

WebSphereApplication Server

This section shows the step by step approach to backup the River Bend Portal environment:

1. A backup maintenance window was scheduled for Saturday nights. In your environment you will want to determine the day and time of that day when the load on your environment is the lowest.

2. A decision was made to do the backups on one Portal node at time since there are only two nodes on the River Bend production cluster. You will want to find out

- 147 -

the fewest number of Portal nodes in your environment that are capable of handling the load during your maintenance window.

3. The length of the maintenance window was set to one hour. This backup architecture was designed taking into consideration that there is only a total of two nodes and one deployment manager sever to backup. Your environment may be different, for example based on speed of your backup process and the total number of nodes you might need to extend your backup window to several hours.

4. Portal on the first node 01 (WP01) is stopped using the WebSphere Administration console (admin console) on the deployment manager server. The following command can also be used:

\<PORTAL-PROFILE>\bin\stopServer.bat WebSphere_Portal –user wasadmin –password xxxx

Where <PORTAL-PROFILE> is c:\IBM\WebSphere\wp_profile on the RiverBend servers.

5. Node agent is stopped on the same node (WP01) using admin console. This command can also be used from a command window:

<PORTAL-PROFILE>\bin\stopNode.bat –user wpsadmin –password xxxx

- 148 -

6. Next we make sure no servers are running on WP01. The following command is used:

<PORTAL-PROFILE>\bin\serverStatus.bat –all –user wpsadmin –password xxxx

7. We took a file system backup using any backup utility. For example if tar is available on your environment, the command will look like:

Tar –cvf Websphere.tar c:\WebSphere

8. Node agent on WP01 is started using the following command

<PORTAL-PROFILE>\bin\startNode.bat

- 149 -

9. We synchronize the nodes with deployment manager using the admin console. Alternatively before the node agent is started the following command can be used to synchronize the node with deployment manager.

<PORTAL-PROFILE>\bin\syncNode.bat dmgr_host dmgr_port –conntype –user wpsadmin –password xxxx

- 150 -

10. Portal server is started on node WP01 using Admin console

11. Portal on the second server is stopped using the admin console. 12. Node agent is stopped on node WP02 13. After that we verify no servers are running on WP02 with the following

command.

<PORTAL-PROFILE>\bin\serverStatus.bat –all –user wpsadmin –password xxxx

14. Then we take a file system backup on the following directories on Node 02:

C:\WebSphere

15. Next we start node agent on WP02. 16. We then synchronize the nodes on the admin console on Deployment Manager. 17. Now, we start Portal on Node WP02. 18. Deployment Manager server is stopped via the following command:

<DMGR-PROFILE>\bin\stopManager.bat –user wpsadmin –password xxx

Where <DMGR-PROFILE> is the profile directory for Deployment manager. For the RiverBend servers is located at

C:\WebSphere\ApplicationServer\profiles\Dmgr01

19. File system backups are taken for the Deployment Manager directories.

- 151 -

20. Database backups are done on the Portal databases using the DB2 backup tools discussed on the following section

21. Deployment manager can be started once the database and file system backups are completed.

The last two steps can be swapped if the portal and application databases have been enabled for online backups.

- 152 -

Best practices and other tools

There are two additional backup tools on this release of WebSphere Application server: BackupConfig and RestoreConfig commands.

BackupConfig Command BackupConfig is a utility used for backing up WebSphere Application server node configurations to zip files. There is no need to stop the servers in order to use this backup tool. However, this command will stop all servers process to complete the backup.

This backup command can be run from:

<WAS_ROOT>\bin directory of the WebSphere Application server.

<PROFILE_ROOT>\bin directory of each individual node.

The directory contents are archived for for

<PROFILE_ROOT>\profile_name\config

The Command syntax is:

backupConfig.bat/sh <backup_filename> [options]

options include – nostop, quiet, -logfile <filename>,- replacelog, -trace, -username <name>, -user <name>, -password password, -help, -?

Please see the infocenter for details.

for River Bend:

c:\WebSphere\bin\backupConfig.bat 110708.zip –nostop

Creates a file called 110708.zip on the WebSphere Deployment manager configuration

restoreConfig command This command can be used to restore a node backed up with the backupConfig command.

- 153 -

All servers on the node are stopped before the configuration is restored. Node synchronization does not occur during restoration. If the restoration directory already exists, it will be renamed before starting the restoration task.

The restoration command can be run from:

<WAS-ROOT>\bin directory of the WebSphere Application server.

<PROFILE-ROOT>\bin directory of each individual node.

The restoration command syntax is:

restoreConfig.bat/sh <backup_filename> [options]

options include – nostop, quiet, -logfile <filename>,- replacelog, -trace, -username <name>, -user <name>, -password password, -help, -?

Please see the infocenter for details.

for River Bend the following command is used:

c:\IBM\WebSphere\bin\restoreConfig.bat 110708.zip –nostop

- 154 -

XMLAccess script tool This command is used to export an entire or partial WebSphere Portal configuration to a single XML document. This exported XML can be imported to the same or to a different portal installation.

On the RiverBend project we used the following command to backup the Welcome page on the production site:

Xmlacces.bat –in XML_File –user wpsadmin –password xxxx –url http://wps02.itso.ibm.cm/wps/config -out Result.xml

Limitations of the XML script command include:

• XMLAccess is not designed for full backups and recovery purposes. • A complete XML export of a Portal configuration is not sufficient to re-create the

portal. • The XML configuration interface was not designed to deal with large volumes of

data.

Additionally, you will also need WAR files for all portlet applications, custom theme, skins and screen resources and any portal services files.

- 155 -

Other tools Keep in mind you may want to backup additional portal resources. Some tools used in typical portal projects include:

IBM Tivoli Storage Manager This tool is used to automate data backup and restore functions and centralized storage management operations. It offers the following features:

• Backup and recovery management • Hierarchical storage management • Archive management

- 156 -

DB2 Database tools

The contents of the WebSphere Portal configuration database include:

• Page layouts, • access control lists, • user customizations, • Overall portal configuration.

Follow these procedures to backup the portal databases:

For cloudscape:

1. Copy the cloudscape directory to a <backup> location

For River Bend development server:

2. Copy C:\IBM\WebSphere\PortalServer\cloudscape to c:\Temp\cloudscape_backup

For DB2:

Use the DB2 control center

3. Expand Databases

- 157 -

Select a database and right click

Backup the following Portal Databases:

• COMMUN – The community database • CUSTOM – The customization database • FDBKDB – Feedback database • JCRDB – java content repository • LMDB - Likeminds database • RELEASE – Release database

4. Select Backup -> Database

- 158 -

5. Select the Image type

- 159 -

6. Select the backup type. Please note this screen shot is for a default offline database backup. It is consider a good practice to enable online backups on your portal databases.

- 160 -

7. Enter additional performance parameters.

- 161 -

8. Choose the type of schedule

- 162 -

9. Click on finish.

- 163 -

Please notice: on this screen shot, a network drive was mapped to the ‘z’ drive.

For other supported database servers, use vendor provided backup tools.

- 164 -

Enabling DB2 for on-line backup In order to ensure 24x7 access to the portal databases in an IBM DB2 environment, the portal databases must be enabled for online backup. If the databases are not enabled for online backup then during an offline backup of the databases portal will not be able to access the database being backed up which can cause an outage for portal. Once a database is enabled for online backup, during a backup portal will be able to continue to access the database. The steps to enable a database for online backup are as follows: Note: Items in red italic need to be updated to match your environment.

1. Modify the database configuration parameter TRACKMOD to ON db2 update database configuration for db_name using TRACKMOD ON

2. Modify the database configuration parameter LOGARCHMETH1 to point to a location in the filesystem with sufficient space for db2 logs

db2 update database configuration for db_name using LOGARCHMETH1 disk:c:\db2_logs Note: The logs are needed for rollforward recovery if needed. Also, they can be archived to other locations besides disk. Refer to the DB2 Info Center for further configuration options.

3. Do a full offline backup of the database db2 backup database db_name to c:\db2_backups Note: A full offline backup can only occur if no other applications or users are connected to the database. The db2 list applications command can be used to verify if others are accessing the database.

Once a database is enabled for online backup, the database can be backed up as either a full backup or an incremental backup. An incremental backup only does a backup of the changes since the last full or incremental backup. For a full discussion of online backup strategies refer to the DB2 Info Center. The command to do a full online backup is:

db2 backup database db_name online to c:\db2_backups

References used in section 7 IBM WebSphere Portal V6 Self Help Guide http://www.redbooks.ibm.com/abstracts/redp4339.html?Open IBM WebSphere Portal V6 Self Help Guide, Appendix B. Maintenance: Fix strategy, backup strategy, and migration strategy http://w3.itso.ibm.com/abstracts/redp4339.html?Open