While you need to deploy your portal application to the administration server, the administration server is not typically used to serve pages for portal applications.

Creating Managed Server Domains

Now that you have configured your domain, including defining your managed servers, you can create individual domains to be used for your cluster using the domain Configuration Wizard. This is necessary because even though the managed servers are defined in the cluster's domain, when run on a different physical machine you still need a domain directory to run the managed servers.

WebLogic Portal must be installed on all managed servers.

In addition, you can see a demo of how to create a managed server.

To create a new managed server, launch the Configuration Wizard.
Choose to Create a new WebLogic configuration and click Next.
In the Select a Configuration Template window, select Basic WebLogic Portal Domain and click Next.
In the Choose Express or Custom Configuration window, select Express and click Next.
In the Configure Administrative Username and Password window, enter a username and password for the server and click Next.

This information will not typically be used, because you will bind this server to the administration server using the administration server's credentials.

In the Configure Server Start Mode and Java JDK, select Production Mode and the SDK (JDK) you will use with the domain. Click Next.

It is important you choose the same JDK across all instances in the cluster.

In the Create WebLogic Configuration window, choose the directory you want to install to, and in the Configuration Name field, enter a domain name to use. For best practices, choose a domain name like `managedServer1', `managedServer2', and so on.
Click Create.
When the domain is created, click Done.

Once you have created a domain for a managed server, you can reuse the same domain for your other managed server on the same machine by specifying different servername parameters to your startManagedWebLogic script, or create new managed domains using the domain Configuration Wizard.

Starting Managed Servers

There are numerous ways to start a managed server and bind it to your administration server, including using Node Manager. For your initial setup, you may want to use the startManagedWebLogic script in the domain root directory. You can run this script by specifying the name of the managed server for this server instance and the URL of the administration server. Before starting the script, you should edit it and give the managed server more memory than it is allocated by default. This can be done by specifying a new MEM_ARGS setting. For example, change the memory allocation to -Xms512m -Xmx512m.

After starting a managed server, you can browse your portal application by going to the appropriate URL on the managed server instance. To provide your users a single point of entry to your cluster, as well as support session failover, you will need to configure a proxy server.

Configuring your proxy server

For instructions on configuring a proxy plugin for WebLogic, see "Configure Proxy Plugins" in Using WebLogic Server Clusters at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/cluster/setup.html#684345.

There are no WebLogic Portal-specific configuration tasks when setting up a proxy plug-in.

Deploying a Portal Application to the Cluster

This section contains instructions for redeployment, partial redeployment, and iterative deployment of datasync data, such as user profile properties, user segments, content selectors, campaigns, discounts, and other property sets.

Redeploying a Portal Application

You can use the WebLogic Server Administration Console or weblogic.Deployer tool to redeploy an updated portal application to your production server. See "weblogic.Deployer Utility" in Deploying WebLogic Server Applications at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/deployment/tools.html.

The following batch file is an example of how to use weblogic.Deployer to redeploy a portal application to production.

@echo off

echo Redeploys a Portal Web Project to a Server or Cluster

echo First Parameter is the name of the Server or Cluster

echo Second Parameter is the name of the Application

echo Third Parameter is the administrative username for the Portal Server

set SERVER=%1

set APPNAME=%2

set USERNAME=%3

echo server = %SERVER%

echo appname = %APPNAME%

echo username = %USERNAME%

java weblogic.Deployer -redeploy -username %USERNAME% -name %APPNAME% -targets %SERVER%

Partial Redeployment

In certain situations you can reduce the time needed to redeploy individual pieces of a portal application by using the weblogic.Deployer tool.

If your updates are contained within a particular portal Web application, you can redeploy just that Web application and greatly reduce the time spent in redeployment. This is of use if you have new portlets and Page Flows, but no new EJBs, libraries, or modules (which are enterprise application scoped).

Because a portal Web application has a number of dependencies on WebLogic Workshop control classes, those needed to be redeployed as well. The following batch file can be used to help simplify that process. You will need to have weblogic.Deployer in your classpath, which can be added by running <BEA_HOME>/weblogic81/common/bin/commEnv script.

@echo off

echo Redeploys a Portal Web Project to a Server or Cluster

echo First Parameter is the name of the Server or Cluster

echo Second Parameter is the name of the Application

echo Third Parameter is the name of the Portal Web Application

echo Fourth Parameter is the administrative username for the Portal Server

set SERVER=%1

set APPNAME=%2

set WEBAPPNAME=%3

set USERNAME=%4

echo server = %SERVER%

echo appname = %APPNAME%

echo webappname = %WEBAPPNAME%

echo username = %USERNAME%

set TARGETS=%APPNAME%@%SERVER%

set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/TimerControl_-livsjc6qp6ws@%SERVER%

set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/p13controls_k3cw9vg6497r@%SERVER%

set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/MDBListener_-1x0154i4jz0he@%SERVER%

set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/GenericStateless@%SERVER%

set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/ProjectBeans@%SERVER%

java weblogic.Deployer -redeploy -username %USERNAME% -name %WEBAPPNAME% -targets %TARGETS%

Iterative Deployment

This section provides instructions for updating portal application datasync data, such as user profile properties, user segments, content selectors, campaigns, discounts, and other property sets, which must be bootstrapped to the database in a separate deployment process.

Portal Datasync Definitions

Portal allows you to author a number of definition files, such as user profiles and content selectors, that must be managed carefully when moving from development to production and back.

Within WebLogic Workshop, portal definitions are created in a special Datasync Project, exposed in the WebLogic Workshop Application window as a /data subdirectory. (On the file system, the directory exists in the application's /META-INF/data directory.) This project can contain user profile property sets, user segments, content selectors, campaigns, discounts, catalog property sets, event property sets, and session and request property sets.

Datasync Definition Usage During Development

During development, all files created in the datasync project are stored in the META-INF/data directory of the portal application and exposed in WebLogic Workshop in the <portalApplication>/data directory. To provide speedy access from runtime components to the definitions, a datasync facility provides an in-memory cache of the files. This cache intelligently polls for changes to definitions, loads new contents into memory, and provides listener-based notification services when content changes, letting developers preview datasync functionality in the development environment.

Datasync definition modifications are made not only by WebLogic Workshop developers, but also by business users and portal administrators, who can modify user segments, campaigns, placeholders, and content selectors with the Weblogic Administration Portal. In the development environment, both WebLogic Workshop and the WebLogic Administration Portal write to the files in the META-INF/data directory.

Compressed Versus Uncompressed EAR

When deployed into a production system, portal definitions often need to be modifiable using the Weblogic Administration Portal. In most production environments, the portal application will be deployed as a compressed EAR file, which limits the ability to write modifications to these files. In a production environment, all datasync assets must be loaded from the file system into the database so the application can be updated.

Figure 3 shows how the /data directory from the updated portal application is put into a standalone JAR and bootstrapped to the database.

Figure 3 Loading updated datasync files to the database

Alternatively, some production environments deploy their portal applications as uncompressed EARs. In this case, the deployed portal application on the administration server is the primary store of datasync definitions. Work done in the WebLogic Administration Portal on any managed server is automatically synchronized with the primary store.

For both compressed and uncompressed EAR files, you can view and update datasync definitions using the Datasync Web Application.

Datasync Web Application

Each portal application contains a Datasync Web Application located in datasync.war in the application root directory. Typically, the URL to the Datasync Web application is http://<server>:<port>/<appName>DataSync. For example, http://localhost:7001/portalAppDataSync. You can also find the URL to your Datasync Web application by loading the WebLogic Server Administration Console and selecting Deployments > Applications > appName > *DataSync and clicking the Testing tab to view the URL.

The Datasync Web application allows you to view contents of the repository and upload new content, as shown in Figure 4.

Figure 4 Datasync Web application home page

Working with the Repository Browser - When working with the Data Repository Browser, you have the option to work with all the files in the repository using the icons on the left hand side of the page, or drill down into a particular sub-repository, such as the repository that contains all Property Set definitions.

View Contents - To view the contents of a repository, click on the binoculars icon to bring up the window shown in Figure 5.

Figure 5 Browsing the Datasync repository

From this list, click on a particular data item to see it's contents, as shown in Figure 6.

Figure 6 Data item contents

As you can see in the previous figure, you can view the XML data for a particular content item.

Removing content

To remove content from a repository, click on the trash can icon on the left side of the page.

Working with Compressed

When the application is deployed, if the JDBC Repository is empty (no data), then the files in the EAR will be used to bootstrap (initialize) the database. The Datasync assets are stored in the following tables: DATA_SYNC_APPLICATION, DATA_SYNC_ITEM, DATA_SYNC_SCHEMA_URI, and DATA_SYNC_VERSION. The bootstrap operation by default only happens if the database is empty. When you want to do incremental updates, the Datasync Web application provides the ability to load new definitions directly into the database. This can be done as part of redeploying a portal application, or independently using a special JAR file that contains your definitions, as shown in Figure 6, Data item contents, on page 23.

Upload new contents - In the Datasync Web application, there is a button on the left side that looks like a document with 1's and 0's called Bootstrap Data. When you click this icon, the following page appears, which lets you load data into the database.

Figure 7 Uploading new datasync data

When you bootstrap, you can choose a bootstrap source, which is either your deployed portal application or a stand-alone JAR file. For example, if you have an updated portal application that you have redeployed to your production environment, you can add any new definitions it contains to your portal. Alternatively, if you have authored new definitions that you want to load independently, you can create a JAR file with just those definitions and load them at any point.

Either way, when you update the data repository, you can choose to "Overwrite ALL data in the Master Data Repository," "Bootstrap only if the Mastery Repository is empty," or "Merge with Master Data Repository-latest timestamp wins."

Bootstrapping from an EAR - If you are redeploy an existing EAR application and want to load any new definitions into the database, choose the Application Data (META-INF/data) as your bootstrap source, and then choose the appropriate Bootstrap Mode. To ensure you do not lose any information, you may want to follow the instructions in the section entitled, Pulling Definitions from Production on page 25 to create a backup first. It is not possible to bootstrap definition data from an EAR file that is not deployed.

Creating a JAR file - To bootstrap new definition files independently of updates to your portal application, you can create a JAR file that is loaded onto the server that contains the files (content selectors, campaigns, user segments, and so on) that you want to add to the production system.

To do this, you can use the jar command from your META-INF/data directory. For example:

jar -cvf myfiles.jar *

This example will create a JAR file called myfiles.jar that contains all the files in your data directory, in the root of the JAR file. Then, you can bootstrap information from this JAR file by choosing Jar File on Server as your data source, specifying the full physical path to the JAR file and choosing the appropriate bootstrap mode. By running this process you can upgrade all the files that are packaged in your JAR. Controlling the contents of your JAR allows you to be selective in what pieces you want to update.

When creating the JAR file, the contents of the META-INF/data directory should be in the root of the jar file. Do not jar the files into a META-INF/data directory in the JAR file itself.

Validating Contents - After bootstrapping data, it is a good idea to validate the contents of what you loaded by using the View functionality of the Datasync Web application.

Pulling Definitions from Production

Developers and testers may be interested in bringing definitions that are being modified in a production environment back into their development domains. As the modified files are stored in the database, Portal provides a mechanism for exporting XML from the database back into files.

One approach is to use the browse capability of the Datasync web application to view all XML stored in the database in a web browser. This information can then be cut and pasted into a file.

A better alternative is to use the DataRepositoryQuery Command Line Tool, which allows you to fetch particular files from the database using an FTP-like interface.

The DataRepositoryQuery Command Line Tool supports a basic, FTP-style interface for querying the data repository on a server.

The command line class is com.bea.p13n.management.data.DataRepositoryQuery. In order to use it, you must have the following in your CLASSPATH: p13n_ejb.jar, p13n_system.jar, and weblogic.jar.

Run the class with the argument help to print basic usage help.

For example:

set classpath=c:\bea\weblogic81\p13n\lib\p13n_system.jar;
c:\bea\weblogic81\p13n\lib\p13n_ejb.jar;
C:\bea\weblogic81\server\lib\weblogic.jar

java com.bea.p13n.management.data.DataRepositoryQuery help

Options for Connecting to the Server

Several optional command arguments are used for connecting to the server. The default values are probably adequate for samples provided by BEA. In real deployments, the options will be necessary.

Only one of -app or -url may be used, as they represent two alternate ways to describe how to connect to a server.

The URL is the most direct route to the server, but it must point to the DataRepositoryQuery servlet in the Datasync Web application. This servlet should have the URI of DataRepositoryQuery, but you also need to know the hostname, port, and the context-root used to deploy datasync.war in your application. So the URL might be something like http://localhost:7001/datasync/DataRepositoryQuery if datasync.war was deployed with a context-root of datasync.

The -app option allows you to be a bit less specific. All you need to know is the hostname, port number, and the name of the application. If there is only one datasync.war deployed, you do not even need to know the application name. The form of the -app description is appname@host:port, but you can leave out some pieces if they match the default of a single application on localhost port 7001.

The -app option can be slow, as it has to perform many queries to the server, but it will print the URL that it finds, so you can use that with the -url option on future invocations.

Examples

Assuming CLASSPATH is set as previously described, and the default username/password of weblogic/weblogic is valid):

Find the application named p13nBase running on localhost port 7001:

java com.bea.p13n.management.data.DataRepositoryQuery -app p13nBase

Find the application named p13nBase running on snidely port 7501:

java com.bea.p13n.management.data.DataRepositoryQuery -app p13nBase@snidely:7501

Find the single application running on localhost port 7101:

java com.bea.p13n.management.data.DataRepositoryQuery -app @7101

Find the single application running on snidely port 7001:

java com.bea.p13n.management.data.DataRepositoryQuery -app @snidely

Find the single application running on snidely port 7501:

java com.bea.p13n.management.data.DataRepositoryQuery -app @snidely:7501

In each of the examples, the first line of output will be something like this:
Using url: http://snidely:7001/myApp/datasync/DataRepositoryQuery

Usage

The easiest way to use the tool is in shell mode. To use this mode, you just invoke DataRepositoryQuery without any arguments (other than those needed to connect as described previously).

In this mode, the tool will start a command shell (you will see a drq> prompt) where you can interactively type commands, similar to how you would use something like ftp.

Alternatively, you can supply a single command (and its arguments), and DataRepositoryQuery will run that command and exit.

Commands

The HELP command will give you help on the commands you can use. Or use HELP command to get help on a specific command.

The available commands are:

Commands are not case-sensitive, but arguments such as filenames and data item URIs may be. More help than what is listed above can be obtained by using HELP command for the command you are interested in.

Where multiple URIs are allowed (indicated by uri(s) in the help), you can use simple wildcards, or you can specify multiple URIs. The result of the command includes all matching data items.

Options in square brackets ([]) are optional and have the following meanings:

The following example retrieves all assets from the repository as files:

java com.bea.p13n.management.data.DataRepositoryQuery -app mget

Working with Uncompressed

When working with a production server with an uncompressed EAR, the only difference from development mode is that there is no poller thread.

When updating definition files using the WebLogic Administration Portal, the files are updated on the administration server in the deployed uncompressed EAR directory automatically. This means that the WebLogic Administration Portal can be used from any managed server in the cluster, but the primary store always resides on the administration server. If the deployable EAR directory is read-only, the WebLogic Administration Portal cannot be used to modify files.

Making sure you are not overwriting files - When working with an uncompressed EAR file in production, special care needs to be taken when working with definition files. When you redeploy your application to your production environment, the existing definition files are replaced. If you have administrators updating definitions using the WebLogic Administration Portal, their changes will be lost upon redeploying an updated application.

Copying back to development - To prevent overwriting any changes done by administrators to definition files when redeploying a new portal application, you must first copy all the definition files from the administration server back to development manually or using the Datasync Web application.

Rules for Deploying Datasync Definitions

There are a number of general concepts to think about when iteratively deploying datasync definitions into a production system. In general, adding new datasync definitions to a production system is a routine process that you can do at any time. However, removing or making destructive modifications to datasync definitions can have unintended consequences if you are not careful.

When removing or making destructive modifications to datasync definitions, you should first consider whether there are other components that are linked to those components. There are several types of bindings that might exist between definitions. For some of these bindings, it is very important to understand that they may have been defined on the production server using the WebLogic Administration Portal and may not be known by the developers.

One example of bindings is that you may have two datasync definitions bound together. An example of this is a campaign that is based on a user property defined in a user property set. If you remove the property set or the specify property, that campaign will no longer execute properly. In this case, you should update any associated datasync definitions before removing the property set or property.

A second scenario is that you have defined an entitlement rule that is bound to a datasync definition. For example, you might have locked down a portlet based on a dynamic role that checks if a user has a particular user property value. In this case, you should update that dynamic role before removing the property set or property.

A third scenario is that there are in-page bindings between datasync items and Portal JSP tags. An example is a <pz:contentSelector> tag that references a content selector. Update the content selector tag in the production environment before you remove the content selector. This is one type of binding that is only configured in WebLogic Workshop at development time rather than in the WebLogic Administration Portal.

A good guideline for developers is to not remove or make significant changes to existing datasync definitions that are in production. Instead, create new definitions with the changes that are needed. This can be accomplished by creating new versions of, for example, campaigns where there is no chance that they are being used in unanticipated ways. Additionally, do datasync bootstraps of the production system's existing datasync definitions back into development on a regular basis.

Removing Property Sets

When you remove a property set, any existing values being stored locally by portal in the database will NOT be removed automatically. You need to examine the PROPERTY_KEY and PROPERTY_VALUE tables to clean up the data if desired.

Propagating LDAP and Portal Database Data

The previous sections provided instructions for deploying file-based portal enterprise applications and updating datasync definitions. The WebLogic Portal Propagation Utility lets you propagate application LDAP and database data from one server to another. The Propagation Utility let's you propagate the following data:

The propagation utility is a portal Web application packaged inside an enterprise application archive (.ear). The propagation utility is deployed on both the domain containing the LDAP and database data (the source server) and the domain that will receive that data (destination server).

Figure 8 shows the propagation utility interface.

Figure 8 The WebLogic Portal Propagation Utility

The propagation utility is a self-contained application that does not require you to open or configure it using WebLogic Workshop.

The main use case for the propagation utility is moving data from a staging environment to a production environment. However, another valid use case is moving data from production back to staging in order to simulate the current production environment on staging.

In a clustered environment, propagate only from the source administration server to the destination administration server. The data is then automatically propagated from the destination administration server to the managed servers in the cluster.

Database Requirements - You must propagate between the same type of database, and you must be able to simultaneously connect to the source and destination databases. You must also have a non-transactional (non-XA) database driver for your database installed on the source server.

The following sections show you how to download, deploy, and use the propagation utility.

Getting the Latest Portal Propagation Utility

Contact BEA Support for the latest version of the Propagation Utility.

About the Propagation Utility Files

The propagation utility download contains the following files:

• readme.html - Provides abbreviated overview and setup instructions, as well as known issues related to the propagation utility.
• PortalPropagationEntApp.ear - The enterprise application archive containing the propagation utility Web application, which must be deployed on the source and destination servers.
• pdef.zip - The archive containing the following files to enable portal database propagation (not LDAP propagation):
• pdef_81.xml - Contains the configuration for propagating portal database data. You can modify this file to customize what is propagated. See the help on the Propagation Utility's DBMS portlet for details.
• portal-propagation_2_0.xsd - The scheme for pdef_81.xml. Do not modify this file.

Setting Up and Deploying the Propagation Utility

This section shows you how to set up and deploy the propagation utility. Table 2 provides an overview of the configuration necessary on both the source and destination servers. Detailed instructions follow the table.

In the following installation steps, starting with step 6., the order for setting up JDBC, JMS, and deploying the propagation application is arbitrary. You can perform those steps in any order.

To install the WebLogic Portal Propagation Utility:

Make sure you have the latest version of the propagation utility from BEA Support.
On both the source and destination servers, create a directory for the utility from which you want to deploy the utility's enterprise application, and extract the utility to that directory.
After you extract the utility, you will see an archive called pdef.zip. Extract this archive to the domain root directory on both the source and destination servers.

For example, if your destination domain directory on both servers is /myDomain, extract pdef.zip into that directory on both servers. The /myDomain/pdef/ directory is created automatically.

Open both the source and destination /pdef/pdef_81.xml files in an editor.

In the top-level <portal-propagation> element of both files, change the default values of the source-data-source-name and destination-data-source-name attributes. Make a note of the values you enter. You will use them in later steps to configure the JDBC database connections on the source server.

For example:

<portal-propagation
xmlns="http://www.bea.com/portal/xsd/propagation/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/portal/xsd/propagation/2.0 portal-propagation_2_0.xsd"
source-data-source-name="srcDataSource"
destination-data-source-name="destDataSource"
insert-new-records="true"
update-existing-records="true">

Save and close the files.

Make sure the source and destination servers are running. If you are using clusters for your source and destination, make sure the administration servers are running.
Add non-transactional (non-XA) JDBC connections and data sources on the source server. In this step, you will set up a source JDBC connection and data source and a destination JDBC connection and data source, both on the source server. This step requires that you have a non-XA database driver installed for your database.

Note: The engine that propagates portal database data needs a non-XA connection pool and data source on the source server for both the source and destination databases. Do not attempt to reuse the existing WebLogic Portal connection pool and data source for propagation, because the server will use a transaction manager and attempt to set up the database propagation as a distributed transaction. Propagation will then fail because the propagation engine needs to manage the transaction itself.

Start the WebLogic Server Administration Console on the source server. For example, http://stagingAdminServer:7001/console.
Create the connection pool for the source server. In the left navigation pane, expand Services > JDBC and click Connection Pools.
In the right pane, click Configure a new JDBC Connection Pool.
On the Configure a JDBC Connection Pool page, select your database type, select a non-XA database driver for it, and click Continue.
On the page that appears, enter the following:

Name	Any name for the source connection pool.
Database Name	(PointBase) Enter the database name. The default is workshop.
Host Name	Enter the source database server name.
Port	Enter the port number of the source database.
Database User Name	Enter the database username for authentication.
Password/Confirm	Enter/confirm the user's password.


 
Click Continue. You can then test the database connection by clicking Test Driver Configuration.
Configure the destination server connection pool on the source server. Click Connection Pools in the left pane, click Configure a new JDBC Connection Pool in the right pane, select your database type and the non-XA driver, and click Continue.
On the page that appears, enter the following:

Name	Any name for the destination connection pool.
Database Name	(PointBase) Enter the database name. The default is workshop.
Host Name	Enter the destination database server name.
Port	Enter the database port on the destination server.
Database User Name	Enter the database username for authentication.
Password/Confirm	Enter/confirm the user's password.


 
Click Continue. You can then test the database connection by clicking Test Driver Configuration.

Your connection pools are configured. Now configure your data sources on the source server to correspond to the connection pools.

Create the data source for the source database. In the left navigation pane, expand Services > JDBC and click Data Sources.
In the right pane, click Configure a new JDBC Data Source.
On the Configure a JDBC Data Source page, in both the Name and JNDI Name fields, enter the value of the source-data-source-name attribute you entered in the /pdef/pdef_81.xml file. For example, enter srcDataSource.
Deselect the Honor Global Transactions option to make the data source non-XA, as shown in Figure 9.

Figure 9 Deselect Honor Global Transactions to make the data source non-XA




 
Click Continue.
On the page that appears, select the corresponding source connection pool (for example, srcPool), and click Continue.
On the page that appears, select the target server (the administration server in a cluster), and click Create.
Now create a second data source on the source server for the destination database. In the left navigation pane, expand Services > JDBC and click Data Sources, and in the right pane click Configure a new JDBC Data Source.
On the Configure a JDBC Data Source page, in both the Name and JNDI Name fields, enter the value of the destination-data-source-name attribute you entered in the /pdef/pdef_81.xml file. For example, enter destDataSource.
Deselect the Honor Global Transactions option to make the data source non-XA, as shown in Figure 9.
Click Continue.
On the page that appears, select the corresponding source connection pool (for example, destPool), and click Continue.
On the page that appears, select the target server (the administration server in a cluster), and click Create.

Connection pool and data source setup is complete. Create connection pools and data sources on any servers that will serve as source servers. For example, set up connection pools and data sources on the production server if you want to propagate back to a staging server.

Create JMS queues for the propagation utility on both servers. While the propagation utility does not use JMS, performing these steps eliminates JMS exceptions that do not affect propagation.
Start the WebLogic Server Administration Console on one of the servers. For example, http://productionAdminServer:7001.
In the left navigation pane, expand Services > JMS > Servers > cgJMSServer (or the server name you used when you set up the domain), and click Destinations.

Note: You may see a list of existing JMS queues you have configured. You must still create the JMS queues for the propagation utility because it runs in its own Web application.

In the right pane, click Configure a new JMS Queue.
In Create a New JMS Queue window, on the General tab, enter the following in the Name and JNDI Name fields:

PortalPropagation.queue.AsyncDispatcher_error

Click Create.
Click the Redelivery tab and change the Redelivery Limit value to 0 (zero).
Click Apply.
Create a second JMS Queue. Click Destinations in the left pane, and click Configure a new JMS Queue in the right pane.
Enter the following in the Name and JNDI Name fields:

PortalPropagation.queue.AsyncDispatcher

Click Create.
Click the Redelivery tab, and in the Error Destination field select PortalPropagation.queue.AsyncDispatcher_error.
Click Apply. The JMS queues on the first server are configured.
On the other server (source or destination), perform the previous steps to set up the two JMS queues.
Deploy the propagation utility PortalPropagationEntApp.ear on the source and destination servers.
Start the WebLogic Server Administration Console on the source server. For example, http://stagingAdminServer:7001/console.
In the left navigation pane, expand Deployments and click Applications.
In the right pane, click Deploy a new Application.
In the Deploy a New Application window, use the Location links to select the directory containing PortalPropagationEntApp.ear (the directory to which you extracted the propagation utility).
When PortalPropagationEntApp.ear appears in the list, select the option button next to it and click Continue.
On the page that appears, click Deploy.
On the page that appears, deployment is complete when the Status of Last Action column shows the message "Success."
On the other server (source or destination), perform the previous steps to deploy PortalPropagationEntApp.ear.

Note: Windows only - If you receive the following type of exception while trying to deploy:

java.lang.InternalError: IO error while trying to compute name from: <path>

it probably means the path to your server exceeds 254 characters. As a workaround, shorten the path to the server for the domain receiving the exception. For example, if your domain path is C:\bea\user_projects\domains\destinationDomain, move the domain to something like C:\destinationDomain.

Starting and Using the Propagation Utility

Start the propagation utility on the source server. Enter the following URL in a browser: http://<host>:<port>/PortalPropagation/wlp81Prop.portal. (The propagation utility does not have to be started on the destination server. It must only be deployed.)
On the Login & Setup page, log in as a user in the Administrators user group.
In the Destination Server Setup portlet, change localhost:7001 to the host:port of the destination domain, and enter the username and password of a member of the Administrators group in the destination domain. Click Set Up & Test Connection to connect to the destination server.
Go to the DBMS page to propagate portal database data to the destination server.
Go to the LDAP page to to propagate roles, delegated administration definitions, and visitor entitlement definitions, or view users and groups (read-only).

Help with the Portlets - The propagation portlets are self-documented. For information on using a portlet, click the help icon on the portlet titlebar.

Understanding Portal Resources

The Portal Library contains books, pages, layouts, portlets, desktops, and other types of portal-specific resources. Using the WebLogic Administration Portal, these resources can be created, modified, entitled, and arranged to shape the portal desktops that end users access.

Figure 10 shows an image of the portal resource tree in the WebLogic Administration Portal. The library contains the global set of portlets and other resources, while the Portals node contains instances of those resources, such as the colorsSample desktop and its pages, books, and portlets.

Figure 10 Portal resources library

Each of these resources is defined partially in the portal database so they can be easily modified at run time. The majority of resources that exist are created by an administrator, either from scratch or by creating a new desktop from an existing .portal template file that was created in WebLogic Workshop.

However, portlets themselves are created by developers and exist initially as XML files. In production, any existing .portlet files in a portal application are automatically read into the database so they are available to the WebLogic Administration Portal.

The following section addresses the lifecycle and storage mechanisms around portlets, since their deployment process is an important part of portal administration and management.

Portlet Deployment Lifecycle

During development time, .portlet files are stored as XML in any existing portal Web application in the Portal EAR. As a developer creates new .portlet files, a file poller thread monitors changes and loads the development database with the .portlet information.

In a production environment, .portlet files are loaded when the portal Web application that contains them is redeployed on the administration server. This redeployment timing ensures that the content of the portlet, such as a JSP or Page Flow, is available at the same time as the .portlet file is available in the Portal Library. The administration server is the chosen master responsible for updating the database so that there are no contention issues around every server in the production cluster trying to write the new portlet information into the database at the same time. When deploying new portlets to a production environment, target the portal application for redeployment on the administration server.

Database Structure for Storing Portlets

When a portlet is loaded into the database, the portlet XML is parsed and a number of tables are populated with information about the portlet, including PF_PORTLET_DEFINITION, PF_MARKUP_DEFINITION, PF_PORTLET_INSTANCE, PF_PORTLET_PREFERENCE, L10N_RESOURCE, and L10N_INTERSECTION.

PF_PORTLET_DEFINITION is the master record for the portlet and contains rows for properties that are defined for the portlet, such as the definition label, the forkable setting, edit URI, help URI, and so on. The definition label and Web application name are the unique identifying records for the portlet. Portlet definitions refer to the rest of the actual XML for the portlet that is stored in PF_MARKUP_DEF.

PF_MARKUP_DEF contains stored tokenized XML for the .portlet file. This means that the .portlet XML is parsed into the database and properties are replaced with tokens. For example, here is a snippet of a tokenized portlet:

<netuix:portlet $(definitionLabel) $(title) $(renderCacheable) $(cacheExpires)>

These tokens are replaced by values from the master definition table in PF_PORTLET_DEFINITION, or by a customized instance of the portlet stored in PF_PORTLET_INSTANCE.

The following four types of portlet instances are recorded in the database for storing portlet properties:

• Primary - Properties defined in development and stored in the .portlet file.
• Library - Properties defined in the Portal Library, which may be changed using the WebLogic Administration Portal.
• Admin - A customized instance of the portlet in a desktop. This allows you to customize a portlet in a particular way for a desktop without affecting other instances of the portlet in other desktops.
• User - User-customized instances of the portlet defined in the Visitor Tools.

PF_PORTET_INSTANCE contains properties for the portlet for attributes such as DEFAULT_MINIMIZED, TITLE_BAR_ORIENTATION, and PORTLET_LABEL.

If a portlet has portlet preferences defined, those are stored in the PF_PORTLET_PREFERENCE table.

Finally, portlet titles can be internationalized. Those names are stored in the L10N_ RESOURCE table which is linked using L10N_INTERSECTION to PF_PORTLET_DEFINITION.

Removing Portlets from Production

If a portlet is removed from a newly deployed portal application, and it has already been defined in the production database, it is marked as IS_PORTLET_FILE_DELETED in the PF_PORTLET_DEFINITION table. It will then show up as grayed out in the WebLogic Administration Portal, and user requests for the portlet if it is still contained in a desktop instance will return a message that says the portlet is unavailable.

Zero Downtime Architectures

One limitation of redeploying a portal application to a WebLogic cluster is that during redeployment users cannot access the site. For enterprise environments where it is not possible to schedule down time to update a portal application with new portlets and other components, a multi-cluster configuration lets you keep your portal application up and running during redeployment.

The basis for a multi-clustered environment is the notion that you have a secondary cluster to which user requests are routed while you update the portal application in your primary cluster.

For normal operations, all traffic is sent to the primary cluster, as shown in Figure 11. Traffic is not sent to the secondary cluster under normal conditions because the two clusters cannot use the same session cache. If traffic was being sent to both clusters and one cluster failed, a user in the middle of a session on the failed cluster would be routed to the other cluster, and the user's session cache would be lost.

Figure 11 During normal operations, traffic is sent to the primary cluster

Step 1 - All traffic is routed to the secondary cluster, then the primary cluster is updated with a new Portal EAR, as shown in Figure 12. This EAR has a new portlet, which is loaded into the database.

Figure 12 Traffic is routed to the secondary cluster; the primary cluster is updated

Routing requests to the secondary cluster is a gradual process. Existing requests to the primary cluster must first end over a period of time until no more requests exist. At that point, you can update the primary cluster with the new portal application.

Step 2 - All traffic is routed back to the primary cluster, and the secondary cluster is updated with the new EAR, as shown in Figure 13. Because the database was updated when the primary cluster was updated, the database is not updated when the secondary cluster is updated.

Figure 13 Traffic is routed back to the primary cluster; the secondary cluster is updated

Even though the secondary cluster does not receive traffic under normal conditions, you must still update it with the current portal application. When you next update the portal application, the secondary cluster will temporarily receive requests, and the current application must be available.

In summary, to upgrade a multi-clustered portal environment, you switch traffic away from your primary cluster to a secondary one that is pointed at the same portal database instance. You can then update the primary cluster and switch users back from the secondary. This switch can happen instantaneously, so the site experiences no down time. However, in this situation, any existing user sessions will be lost during the switches.

A more advanced scenario is a gradual switchover, where you switch new sessions to the secondary cluster, and after the primary cluster has no existing user sessions you upgrade it. Gradual switchovers can be managed using a variety of specialized hardware and software load balancers. For both scenarios, there are several general concepts that should be understood before deploying applications, including the portal cache and the impact of using a single database instance.

Single Database Instance

When you configure multiple clusters for your portal application, they will share the same database instance. This database instance stores configuration data for the portal. This can become an issue, because when you upgrade the primary cluster it is common to make changes to portal configuration information in the database. These changes are then picked up by the secondary cluster where users are working.

For example, redeploying a portal application with a new portlet to the primary cluster will add that portlet configuration information to the database. This new portlet will in turn be picked up on the secondary cluster. However, the new content (JSP pages or Page Flows) that is referenced by the portlet is not deployed on the secondary cluster.

Portlets are only invoked when they are part of a desktop, so having them available to the secondary cluster will have no immediate effect on the portal that users see. However, adding a new portlet to a desktop with the WebLogic Administration Portal will immediately affect the desktop that users see on the secondary cluster. In this case, that portlet would show up, but the contents of the portlet will not be found.

To handle this situation you have several options. First, you can delay adding the portlet to any desktop instances until all users are back on the primary cluster. Another option is to entitle the portlet in the library so that it will not be viewable by any users on the secondary cluster. Then add the portlet to the desktop, and once all users have been moved back to the primary cluster, remove or modify that entitlement.

A special case to be aware of is if you are updating an existing portlet's content URI to a new location that is not yet deployed. For this reason, updating the content URI of a portlet should be done with care or as part of a multi-phase update.

Another important consideration when running two portal clusters simultaneously against the same database is the portal cache.

Portal Cache

WebLogic Portal provides facilities for a sophisticated cluster-aware cache. This cache is used by a number of different portal frameworks to cache everything from markup definitions to portlet preferences. Additionally, developers can define their own caches using the portal cache framework. The portal cache is configured in the WebLogic Administration under Configuration Settings / Service Administration / Cache Manager. For any cache entry, the cache can be enabled or disabled, a time to live can be set, the cache maximum size can be set, the entire cache can be flushed, or you can invalidate a specific key.

When a portal framework asset that is cached is updated, it will typically write something to the database and automatically invalidate the cache across all machines in the cluster. This process keeps the cache in sync for users on any managed server.

When operating a multi-clustered environment for application redeployment, special care needs to be taken with regard to the cache. The cache invalidation mechanism does not span both clusters, so it is possible to make changes on one cluster that will be written to the database but not picked up immediately on the other cluster. As this situation could lead to system instability, it is recommended that during this user migration window the caches be disabled on both clusters. This is important when you have a gradual switchover between clusters versus a hard switch that drops existing user sessions.