Production Operations User Guide

Inside the Propagation Utility

The Propagation Utility allows you to propagate the configuration of one portal environment to another. This chapter provides information that you need to know before using the Propagation Utility. For usage information about this utility, see Using the Propagation Utility. For a description of limitations in the current release of the Propagation Utility, see the WebLogic Portal SP4 Propagation Patch Release Notes.

The sections included in this chapter are:

The Propagation Utility Sequence

Propagation using the Propagation Utility consists of two primary tasks:

First you export a system inventory from a source system, which is typically a staging system. This exported inventory list describes the entire Enterprise application configuration, as contained in the database for that system. The exported inventory is stored in the form of XML files, which are grouped into a single ZIP file.
Then you import and commit the inventory to a destination system, which is typically a production system. The following text summarizes the steps that you perform as part of the import process:

Set the scope - You choose a scope for the propagation; scopes include Enterprise application, Portal web applications (as a group), individual Portal web application, portal, and desktop. For more information on scope, see Setting the Scope.
Choose policies - Policies are well-defined conditions under which source assets will (or will not) be merged into the destination database. For more information on policies, see Conflict Resolution Using Policies.
Preview changes - The Propagation Utility finds and displays the changes that will occur when you choose to commit the propagation, based on the scope and policies that you select. For more information on the types of data that can be propagated, see Propagation Scope Reference Table.
Commit the changes - When you commit the changes, the Propagation Utility performs the changes based on the previewed change manifest.

General Propagation Guidelines

The following sections describe some general considerations to keep in mind as you prepare to use the Propagation Utility.

Propagating in a Clustered Environment

In a clustered environment, propagate from the source server to the specific managed server on the destination.

Propagating Across Networked Systems

Keep in mind that the Propagation Utility is a Web-based application that runs on the server that you are importing to or exporting from. If you have a firewall between the source and the destination system that blocks access from a client browser, give access to the client machine or run the import process from the destination machine.

Before You Begin

The following sections describe some preparation tasks to perform before using the Propagation Utility. For additional information about the propagation planning process, see Developing a Propagation Strategy.

Perform a Data Backup

Back up your WebLogic LDAP repository using the steps in the Recovering Failed Servers section of the WebLogic Server documentation.

Back up your database using the the vendor tools appropriate for your environment. Save a copy of the deployed application that you are propagating; you will be deploying an EAR to the existing application, which will overwrite the current configuration.

Plan to Inactivate the System During the Import Process

The Propagation Utility does not provide the ability to quiesce the system (that is, disable modification of portal data via the Administration Portal). You might want to prevent users from changing portal data during a propagation by redirecting WebLogic Administration Portal URLs to a maintenance page. It is very important that you make no changes to the production system after you load and validate the inventory listing during the import portion of the propagation. For more information, see Acknowledging the Quiescence Requirement.

Install the Patch

Before running the Propagation Utility you must have already installed appropriate software. For instructions, see Installing the Propagation Software.

Customize the Session Timeout and Inventory/Log File Location (Optional)

You can change the default location of the verbose log files and inventory files, and change the session timeout period.

To edit these values, uncompress the propagation.war file, which is located in the following directory:

patchpath\8.1 SP4 Patch\Propagation Tool

where patchpath is the root directory where you unzipped the patch.

Edit the web.xml file to make any changes that you want; this file is located here:

patchpath\8.1 SP4 Patch\Propagation Tooll\WEB-INF

When you finish editing the file, remember to compress the files to recreate the propagation.war file.

Session Timeout Value

To change the timeout period, expressed in minutes, edit the web.xml file to change the session-timeout value:

<session-config> <session-timeout>15</session-timeout> </session-config>

Inventory and Log File Location

To change the default location of the generated inventories that the Propagation Utility produces and the default location for the Propagation Utility's verbose log files, edit the web.xml file to change param-value:

<context-param> <param-name>oamDataFilesystemPath</param-name> <param-value>d:/propagation/81xDomain/inventories</param-value> <description>Base folder path for runtime data, such as inventory exports.</description> </context-param>

For more information on the log files that the Propagation Utility produces, see Reviewing Propagation Utility Export Log Files and Reviewing the Import Log Files.

Deploy the J2EE Application (EAR)

If you created new resources for your web application using WebLogic Workshop, including portlets, portals, books, pages, custom layouts, look and feels, menus, shells, themes, JSPs, or Java classes, you must deploy the J2EE application from the source system to the destination system at some point prior to committing the changes with the Propagation Utility. When you deploy the J2EE application, changes reflected in the EAR file may or may not be propagated automatically, depending on whether your server is in production mode or development mode. For more information, see General Propagation Scenarios and Scenario 2: Redeploying an EAR file. For detailed information on deploying EAR files, see Preparing and Deploying the EAR File.

Tip: It is not required that you deploy your J2EE application prior to beginning the Propagation Utility; the Propagation Utility Web-based interface contains a reminder page at the required stage in the propagation process. However, deploying the application beforehand is a good practice.

If you commit propagation changes without deploying the J2EE application, the inventory listing includes the new resources, but the resources are not displayed in the portal library on the destination system and the following destination database tables are not updated with new data:

PF_MENU_DEFINITION
PF_LAYOUT_DEFINITION
PF_LOOK_AND_FEEL_DEFINITION
PF_SHELL_DEFINITION
PF_THEME_DEFINITION
PF_PORTLET_DEFINITION

For more information on these database tables and how they are used, see the BEA WebLogic Portal Database Administrator Guide.

Make Required Manual Changes

Because the Propagation Utility does not propagate the complete set of portal resources from the source to the destination system, there might be cases where propagated data depends on other data that is not propagated. For example:

Visitor entitlement roles are propagated to the destination but any related users and groups are not, so you must manually add those related users and groups on the destination system.
If you are propagating any data related to new content repositories, you must create the new content repositories on the destination system before using the Propagation Utility.

For a list of propagated and non-propagated resources, see Propagation Scope Reference Table.

The Propagation Utility Web-based interface includes a page that lists pending changes that require associated manual updates. Review this list of changes to verify that you have already performed all required manual changes.

To view an example of a manual change listing, see Making Manual Changes Prior to Propagation.

Propagation Scope

To understand how portal assets are propagated, it is crucial to understand propagation scope. The Propagation Utility detects differences that exist between the source and destination systems and creates a nested list of possible scopes. From this list, you may select a specific scope for the propagation. For instance, if you select web application scope, all assets in the web application are propagated. If you select desktop scope, only the assets associated with a specific desktop are propagated.

Setting the Scope

You specify the scope of a propagation during the import process. You can select to scope the propagation at several levels of granularity, depending on where differences exist between your two systems.

Enterprise application - Propagates all detected changes for the Enterprise application to the destination system.

Note: The Propagation Utility can be used to move data between different instances of the same enterprise application; it does not support propagating from one application to another.

Portal Webapps - Propagates as a group all of the portal framework data for the web applications present in the Enterprise application.
Web application - Propagates all portal framework data within a single web application.
Library - Propagates portal framework Library data for a single web application.
Portal - Propagates as a group all of the desktops in a single portal web application.
Desktop - Propagates all differences within a single desktop. This scope maps to the Export/Import Utility's Admin scope, as described in Using the Export/Import Utility.

Tip: When using the Propagation Utility, the best practice is to scope to the highest level—Enterprise application. This ensures that the destination environment will exactly mirror the source environment. If you scope to a lower level, web application or desktop, the source and destination might be in different states. In this case, additional quality assurance testing may be required on the destination. For details, see Set the Scope to the Enterprise Application Level.

Scope and Library Inheritance

The WebLogic Administration Portal organizes portal resources in a tree that consists of Library resources and desktop resources. Understanding the relationship between Library and desktop resources helps you to understand the effects and consequences of propagation.

Portal Asset Instances and Inheritance

The following text describes the relationships between the following instances of portal assets:

Primary instance - Created in WebLogic Workshop and stored in a .portal or .portlet file
Library instance - Created or updated in the Administration Portal, and displayed in the Portal Resources tree under the Library node
Desktop instance - Created or updated in the Administration Portal, and displayed in the Portal Resources tree under the Portals node
Visitor instance - Created or updated in the Visitor Tools

Creating a New Desktop and Disassembling to the Library

When you create a new desktop using the Administration Portal, you can use an existing portal template. Using a template means that you will be taking the portal resources for your desktop directly from a .portal file that was created in WebLogic Workshop. (The .portal file is also called the primary instance.) When you create a desktop, the portal assets are removed from the .portal file, placed in a database, and surfaced in both the Library and desktop trees of the Administration Portal. Taking the assets from a new desktop instance and placing them in the Library is called disassembling.

At this point, the assets (books, pages, and so on) in the Library (Library instances) are hierarchically related to their corresponding desktop instances. A change to a Library resource, such as a name change, is automatically inherited by the corresponding desktop asset. On the other hand, a change to the desktop asset is not reflected back up the hierarchy.

Note: Changes made to assets are never "reverse inherited" up the hierarchy. A change to a desktop asset is never inherited by its corresponding Library instance. Likewise, a change to a Visitor instance is never inherited by a desktop or Library instance.

New books and pages that you create in a desktop are not disassembled—they are considered to be private to that desktop.

When you propagate a portal using either portal or desktop scope, new pages and books are disassembled to the Portal Library if they do not already exist there.

Decoupling of Property Settings

If an administrator or a visitor (using Visitor Tools) changes the Book Properties of a book or the Page Properties of a page in a desktop, those property settings become decoupled from the settings in the parent book or page in the Library. Page properties include layout and theme, while Book Properties include menus and layout. These properties can be modified in the Administration Portal. When a portal is propagated, any assets that are decoupled in the source application will remain decoupled in the destination.

Propagation Scope Reference Table

This section lists the kinds of portal assets handled by the Propagation Utility and shows you the scoping levels that are available for each type of asset. Table 7-1 helps you choose the appropriate scope for the propagation you wish to perform, and to ensure that the assets you wish to propagate are propagated. For example, some assets, such as dataync data, are only propagated at the Enterprise scope.

This table includes data that can be propagated by the Propagation Utility as well as using the Datasync web application or by deploying the EAR. If you deploy the EAR prior to using the Propagation Utility, as recommended, fewer changes will actually be handled by the Propagation Utility. For details on the Datasync web application, see Using the Datasync Web Application. For details on EAR deployment, see Preparing and Deploying the EAR File.

For more details on manually propagating assets, see Make Required Manual Changes.

Data propagation depends on the scope that you set during the Import task. The following indicators in the table show the applicable propagation scopes for each type of data:

E - Enterprise Application scope
PW - Portal Webapps scope (all web applications that reside in the Enterprise application)
W - Web application scope
L - Web application Library scope
P - Portal scope (all desktops that reside in an individual portal)
D - Desktop scope

For more information about propagation scopes, see Setting the Scope.

Table 7-1 Data Propagation Reference Table

Data Category	Data	Propagation Scope and Description
Framework	Portals	E, PW, W, L, P - fully propagated. D - not applicable. Data at this scope is moved by deploying the EAR.
	Desktops	E, PW, W, L, P, D - fully propagated.
	Books	E, PW, W, L, P, D - fully propagated. Note: The description field content is not propagated; for details see the WebLogic Portal 8.1 SP4 Propagation Patch Release Notes.
	Pages	E, PW, W, L, P, D - fully propagated. In addition, Look and Feel references, such as a dependency between a page and its layout, are propagated. Note: The description field content is not propagated; for details see the WebLogic Portal 8.1 SP4 Propagation Patch Release Notes.
	Portlets	E, PW, W, L, P, D - fully propagated.
	Portlet Preferences	E, PW, W, L, P, D - fully propagated. Note: For the current release, portlet preferences are never deleted from the destination server; changed preference attributes are concatenated rather than updated. For details, see the WebLogic Portal SP4 Propagation Patch Release Notes.
	Portlet Categories	E, PW, W, L - fully propagated. P, D - not applicable. Data at this scope is moved by deploying the EAR.
Framework, continued	Shells	Not applicable. Data at this scope is moved by deploying the EAR.
	Themes	Not applicable. Data at this scope is moved by deploying the EAR.
	Menus	Not applicable. Data at this scope is moved by deploying the EAR.
	Layouts	Not applicable. Data at this scope is moved by deploying the EAR.
	Look and Feels	Not applicable. Data at this scope is moved by deploying the EAR.
Framework, continued	User Customizations	Not propagated. User customizations are preserved on the destination system, but may be modified when imported changes are applied to the destination. For more information, see User Customizations and Propagation.
Datasync	Catalog Property Definitions	E - fully propagated. PW, W, L, P, D - not propagated.
	Content Selectors	E - fully propagated. PW, W, L, P, D - not propagated.
	Discount Definitions	E - fully propagated. PW, W, L, P, D - not propagated.
	Event Definitions	E - fully propagated. PW, W, L, P, D - not propagated.
	Placeholders	E - fully propagated. PW, W, L, P, D - not propagated.
	Request Properties	E - fully propagated. PW, W, L, P, D - not propagated.
	Segments	E - fully propagated. PW, W, L, P, D - not propagated.
	Session Properties	E - fully propagated. PW, W, L, P, D - not propagated.
	User Profile Definitions	E - fully propagated. PW, W, L, P, D - not propagated.
	Campaign Definitions	Not propagated.
Runtime Data	Behavior Tracking Events	Not propagated.
	Orders	Not propagated.
	User Profiles	Not propagated.
Security	Global Roles (created using WebLogic Server)	E, PW, W, L, P, D - fully propagated, except definitions that you create using public entitlement APIs.
	Visitor Entitlement Policy Definitions	E, PW, W, L, P, D - fully propagated, except definitions that you create using your own custom code (APIs).
	Delegated Administration Policy Definitions	E - fully propagated. PW, W, L, P, D - only the roles that are required (that a given asset depends upon) are propagated. These delegated administration policies are propagated: Portal resources (Library and Desktop level) Users and groups Content selectors Campaigns Visitor roles Placeholders Segments Security providers Note that definitions pertaining to Content Management are not propagated.
	Delegated Administration and Visitor Entitlement Roles	E - fully propagated. PW, W, L, P, D - only the roles that are required (that a given asset depends upon) are propagated. Note: Whenever you propagate roles, do so at the Enterprise scope. Otherwise, lower level dependencies and the role hierarchy might not be preserved on the destination. For details, see the WebLogic Portal 8.1 SP4 Propagation Patch Release Notes. Roles that you create using your own custom code (APIs) are not propagated. Users and groups are not propagated, but user and group identification is preserved; you must manually create users and groups that correspond with propagated roles.
	Users	Not propagated; the hashed passwords cannot be propagated.
	Groups	Not propagated.
WSRP	WSRP Registration Data	Not propagated. For more information on WSRP propagation, see WSRP Propagation.
Content Management	All Content Management information, items, types, and metadata	Not propagated.

Security Information and Propagation

Security information consists generally of authentication data and authorization data. As Table 7-2 shows, authorization data consists of roles and policies, while authentication consists of users and groups.

Table 7-2 Types of security data

Authorization

Roles

Visitor entitlement

Delegated administration

Global (defined in WebLogic Server)

Delegated role hierarchy

Stored in internal providers or external providers, such as a custom Authorization provider.

The delegation hierarchy is stored in the database, but optionally can be stored in LDAP.

Policies

Visitor entitlements

Delegated administration

Authentication

Users

Groups

Stored in internal providers or external providers, such as an RDBMS user store or an OpenLDAP. Also stored provider configurations and audit trails.

For more details on the specific data propagated, see Propagation Scope Reference Table.

Authentication information (users and groups) is never propagated by the Propagation Utility. User and group information is often maintained in separate external authentication repositories over which WebLogic Portal has no control.

In addition to user and group information, the Propagation Utility does not propagate the following:

Provider configurations (although they are listed when an application is exported)
Data from external providers
Audit Trails

Because roles contain user and group information, you need to consider how user and group information is stored for your staging and production system; these two systems systems may or may not share the same authentication repositories.

If your systems do not share the same authentication repositories for managing users and groups, then after propagating a portal, you must manually edit each role to add the appropriate users and groups on the destination system. If the systems do share the same authentication repositories, then no manual changes to roles need to be made after a propagation.

For more information on manual propagation changes, see Make Required Manual Changes.

Note: It is a best practice to reference groups, but not specific users, in roles. This practice makes it easier to maintain roles when users need to be added or removed from the system.

User Customizations and Propagation

The typical propagation occurs from a staging environment to a production system. In this scenario, users typically do not have access to the staging environment, and no user customization changes that require propagation would exist. As a result, the Propagation Utility is not designed to propagate user customizations.

User customizations are preserved on the destination, but when you propagate to a destination system, those customizations might be removed or modified on the destination server under certain conditions. For intstance, an administrator might make changes through the Administration Portal that potentially conflict with a given user's customizations. For example, an administrator might delete a particular portlet from the portal that has been added by a user to one of their pages using the Visitor Tools. In this situation, the user's customization is "lost" in the sense that the portlet no longer exists, and as such, will not appear in the user's portal upon the next login.

In general, when changes on a staging system are propagated to the production system, the merging of staged changes and user customizations will occur just as it would if the staged changes were made directly on the production system using the WebLogic Administration Portal.

Datasync Assets and Propagation

The Propagation Utility propagates datasync assets at the Enterprise Application scope only. For more information on datasync propagation, see Moving the Datasync Data.

Conflict Resolution Using Policies

The Propagation Utility merges source and destination data based on policy rules, also called merge rules, that you can configure for your requirements. You can choose to either activate or ignore the policy rules during a propagation. If the policy choices you make here lead to a conflict as the propagation proceeds, policies take precedence in the order shown here.

If an asset exists on the source, but not on the destination, add it to the destination.

If an asset exists on the destination, but not on the source, delete it from the destination.

If an asset exists on the source and the destination, update the destination with the asset's source attributes.

The following sections describe how the Propagation Utility prioritizes and implements policies, and describe some considerations that you must keep in mind as you decide how to set these propagation policies.

Identifying Differences Between Assets

The Propagation Utility creates unique identifiers for portal assets so that they can distinguish whether two assets are the same in the source and destination systems. A portion of this identifier is based on the definition label, or the instance label, which shown in the property editor pane in WebLogic Workshop and the page properties within the WebLogic Administration Portal. Figure 7-1 shows an example of the definition labels as displayed by the WebLogic Administration Portal:

Figure 7-1 Definition Labels

Definition Labels

When you preview changes during the propagation process, you can view the planned changes based on the detected differences between the two systems.

Prioritizing Changes Based on Policies

If a conflict occurs while processing a propagation, the Propagation Utility attempts to handle conflicts according to the policies you created, in the priority order listed previously.

When the Propagation Utility resolves a conflict, the resolutions are listed in the log file that the utility creates during processing, and the web-based Propagation Utility interface will list any changes that occurred in order to resolve conflicts.

Handling Propagation Conflicts

When conflicts arise, policies take precedence in the order in which they appear in the Propagation Utility policies page. The following example describe how the Propagation Utility resolves a conflict when the same page is added to different books on the source and destination.

A user adds Page1 to Book2 on the source system, but another user adds the same Page1 to Book3 on the destination. The rules are defined such that additions to the source are added to the destination, and "deletions" on the source are ignored (that is, if an asset exists on the destination and not on the source, it remains on the destination). Because WebLogic Portal requires that a given page cannot exist in more than one book, the Propagation Utility resolves the conflict by adding Page1 to Book2, and removing it in Book3 on the destination system.

Rolling Back an Import Process

If you must revert to a pre-propagated environment, use the backups that you created before beginning the propagation process. For more information, see Perform a Data Backup.

WSRP Propagation

One of the primary advantages of Web Services for Remote Portlets (WSRP) is that the WSRP model decouples the producers that host and maintain remote services and the consumers that use them. It is important to note that when you create a remote portlet on a consumer, registration information about the consumer is stored on the producer. Registration information includes the registration handle, WSDL URL, and other optional information. When you propagate the consumer from a staging to a production environment, the propagation utility is not directly aware of the producer or of the consumer registration information it maintains.

Two Models for WSRP Propagation

There are two models for working with WSRP propagation across staging and production environments: shared registration and dual registration.

Note: Currently, shared registration is the only model that is supported by WebLogic Portal.

Shared registration — Both the staging and production servers use the same registration handle. After propagating the consumer, the producer cannot distinguish between the staging and production consumer, because they both share the same handle. In effect, both consumers "point" to the same producer. Note that any changes that are made to the producer's portlets will be seen by the consumers in both staging and production. In addition, if a producer is un-registered in the staging environment, it will be un-registered in the production environment as well.
Dual registration — The staging and production environments each use their own registration handle. In this case, configuration changes made in one environment are not visible to the other.

Support for Shared Registration

WebLogic Portal supports only the shared registration model. Because the registration handle is shared by the staging and production environments, the same producer is visible to both environments; therefore, propagation of producer data is not necessary.

The drawback of this model is that it is not possible to "stage" the producer's portlets: any change to a producer portlet will automatically be reflected in both the staging and production systems.

In the future, WebLogic Portal will support WSRP 2.0, which provides support for propagating a producer's state with a dual registration model.

Best Practices

The following sections describe some practices that you should follow to achieve the most predictable and accurate results with the Propagation Utility.

Keep Portal Framework Definition Labels and Instance Labels

When you create new portals and portal resources in WebLogic Workshop, BEA recommends that you change the definition labels and instance labels at that time, to create meaningful names for these resources. Once you have used the Propagation Utility to propagate changes among your environments, it is very important that you do not change these resource names. The Propagation Utility uses definition labels and instance labels in order to identify differences between source and destination systems; inconsistent results might occur if you change these labels within WebLogic Workshop or the WebLogic Administration Portal.

Do Not Manually Replicate Changes Between Environments

Create artifacts in only one environment. If you make changes in both, even if they are identical changes, the utility cannot identify them as being the same changes—propagation is carried out as if they were two separate resources.

Set the Scope to the Enterprise Application Level

Choosing the highest level of scoping for the propagation ensures the that the destination environment will closely mirror the source environment. If you scope to a lower level, such as web application or desktop, the source and destination will inherently be in different states. In this case, additional quality assurance testing may be required on the destination.

Although you can restrict the scope of a propagation, sometimes the utility must implement a higher-level change if a change at that narrower scope depends on a change that occurs at a higher level. For example, if you propagate a desktop that depends on assets in the library, and changes occur for those library assets, the Propagation Utility can cause changes to other desktops even though you set the scope at a desktop level. For more information on the relationships among Portal resources, see Scope and Library Inheritance.