| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.5) Part Number E14245-04 |
|
|
View PDF |
| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.5) Part Number E14245-04 |
|
|
View PDF |
This chapter covers a range of topics related to WebLogic Portal propagation. We recommend that you read this chapter before you attempt to propagate a portal.
Note:
The propagation tools only work with inventories that were created using the same version of WebLogic Portal. For example, you cannot use an inventory generated with WebLogic Portal 10.0 with the propagation tools from a later version of WebLogic Portal.
This chapter includes the following topics:
Section 6.7, "Previewing Changes and Tuning a Merged Inventory"
Section 6.15, "Propagating Datasync Data in Development Mode"
Figure 6-1 shows the basic flow of a typical propagation session. The basic steps illustrated include:
First, you export the portal inventory from the source system and the destination system.
Merge the inventories. These propagation tools let you view and modify the merged inventory files before producing a final inventory file.
Create a final merged inventory. The final inventory represents the combination of the two inventories after all scoping and policy rules have been applied. Scoping is discussed in Section 6.5, "Understanding Scope." Policies are discussed in Section 6.6, "Using Policies."
The final inventory file is then uploaded and committed to the destination server.
Note:
These steps represent a typical propagation session. Other possible uses of the propagation tools exist. For instance, you could export an inventory and immediately (without merging) upload it to the destination and commit it.
The following sections describe some preparation tasks to perform before propagating a portal application. For additional information about the propagation planning process, see Chapter 5, "Developing a Propagation Strategy."
Note:
It is not recommended to propagate between source and destination systems that are running JVMs with different default locales. If the locales differ between the source and destination system, performance will be slower and the localization node of all Portal Framework assets will always be logged as a difference.
The Administration Server must be running when you perform a propagation to allow certain LDAP data to be updated. A propagation can cause the following kinds of LDAP data to be added, deleted, or updated: visitor roles, delegated administration roles, entitlement policies, and delegated administration policies.
Back up your WebLogic LDAP repository using the steps in the "Avoiding and Recovering from Server Failure" in Oracle Fusion Middleware Managing Server Startup and Shutdown for Oracle WebLogic Server.
Back up your database using 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.
Before you import a final inventory to a destination system, take steps to prevent users from changing portal data. When the final inventory is being committed to the destination server, any changes made through the WebLogic Portal Administration Console or certain WLP API calls (such as content management APIs) can lead to unwanted side effects, such as lost data.
The OnlineMaintenanceModeTask Ant task can be used to prevent changes to the destination server. You can also use the WebLogic Portal Administration Console to place a server in maintenance mode. To do this, select the Configuration Settings > Service Administration > Maintenance Mode. For detailed information on OnlineMaintenanceModeTask, see Section 9.1.4, "OnlineMaintenanceModeTask." Oracle Enterprise Pack for Eclipse does not provide a maintenance mode feature.
The Oracle Enterprise Pack for Eclipse propagation feature is installed automatically when you install WebLogic Portal (unless you explicitly exclude it). The propagation Ant tasks require some additional configuration before you can use them. For information on installing and using the Ant tasks, see Chapter 8, "Using the Propagation Ant Tasks."
For information on configuring verbose log files in Oracle Enterprise Pack for Eclipse, see Section 7.9, "Enabling Verbose Logging."
If you created new resources for your web application using Oracle Enterprise Pack for Eclipse, 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 tools.
Tip:
It is a good practice to deploy the EAR file before you export the destination inventory. By doing this, you can reduce the number of manual changes you need to make after you commit the final inventory to the destination.
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 Section 5.7, "General Propagation Scenarios" and Section 5.7.3, "Scenario 2: Redeploying an EAR file." For detailed information on deploying EAR files, see Chapter 4, "Deploying Portal Applications."
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 Oracle Fusion Middleware Database Administration Guide for Oracle WebLogic Portal.
While the propagation tools propagate most portal data, there are some exceptions. Any portal assets that are not propagated must be added to the destination server using the WebLogic Portal Administration Console.
In general, the propagation tools do not propagate the following kinds of data:
Users and groups
Users and groups are, by design, not propagated.
Content repositories
You must create matching content repositories on the destination system before you can propagate content in those repositories.
Note:
The workflow state of content nodes is not preserved during propagation for content items in a managed repository. During propagation, the workflow state of content nodes that were published on the source show up as DRAFT on the destination. To work around this issue, manually go to the destination nodes and publish each of them individually, or use the bulk loading feature in the Administration Console to perform this task.
Out of scope dependencies
If you use the scoping mechanism to exclude assets that other assets depend upon, you must manually add the dependencies to the destination server. See Section 6.5, "Understanding Scope" for more information.
Global roles
WSRP producer registrations (See Section 6.11, "Federated Portal (WSRP) Propagation.")
Note:
For a comprehensive list of propagated and non-propagated portal resources, see Section 6.3, "Propagation Reference Table."
Manual changes are reported to you in the following places:
The OfflineDiffTask and OfflineExtractTask propagation Ant tasks can optionally write a list of manual changes to a file. For details on these tasks, see Chapter 9, "Propagation Ant Task Reference."
All of the propagation Ant tasks allow you to optionally write messages to a log file.
Note:
For a comprehensive list of propagated and non-propagated portal resources, see Section 6.3, "Propagation Reference Table."
All manual adds cause the commit operations to fail. You can override this behavior using an Ant task modifier. Manual updates and deletes are reported as warnings, but do not cause the commit operation to fail. The propagation servlet writes information about all manual elections to the concise log file that is sent back to the client by the propagation servlet. You can view these messages by:
Viewing the server log/console window.
Viewing the concise log file.
If there is a manual add election then the propagation servlet will send back a failure response. This will cause the contents of the concise log file to be displayed in the ant console window. But this only happens if there is an add election (not an update or delete) and only if the default behavior of failing on the presence of a manual add has not been overridden
In Oracle Enterprise Pack for Eclipse, viewing the server log/console window.
In Oracle Enterprise Pack for Eclipse, viewing the concise log file.
In Oracle Enterprise Pack for Eclipse, if there is a manual add election then the propagation servlet will send back a failure response. This will cause the contents of the concise log file to be displayed in a Oracle Enterprise Pack for Eclipse error dialog. But this only happens if there is an add election (not an update or delete) and only if the default behavior of failing on the presence of a manual add has not been overridden.
A Oracle Enterprise Pack for Eclipse propagation session reports manual changes in the following ways:
The Console view displays manual changes.
In the Properties view, the Manual Steps field indicates if propagating the asset requires any manual changes.
In the Merged Files tab, the editor highlights assets that must be manually updated as follows: the asset's name is shown in yellow and an Eclipse warning badge is shown on the asset's icon.
Table 6-1 provides a comprehensive list of the categories and types of data that comprise a portal and whether or not the propagation tools move them. Any type of data that is not propagated by the propagation tools is noted in the Notes column. Data that is not propagated might require a manual change to be made on the destination server. For more information on manual changes, see Section 6.2.7, "Make Required Manual Changes."
Table 6-1 Data Propagation Reference Table
| Data Category | Data | Notes |
|---|---|---|
|
Framework |
Portals Desktops Books |
N/A |
|
Framework |
Pages |
In addition, Look and Feel references, such as a dependency between a page and its layout, are propagated. |
|
Framework |
Portlets |
|
|
Framework |
Portlet Preferences Portlet Categories Community Templates |
N/A |
|
Framework |
Shells Themes Menus Layouts Look and Feels |
Not propagated. Manual change. |
|
Framework, |
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 Section 6.8, "User Customizations and Propagation." |
|
Datasync |
Content Selectors Event Definitions Placeholders Request Properties Segments Session Properties User Profile Definitions Campaign Definitions |
N/A |
|
Runtime Data |
Behavior Tracking Events Orders User Profiles |
Not propagated. |
|
Security |
Global Roles (created using WebLogic Server) |
Global roles are not propagated. Note: Definitions that you create using public entitlement APIs are not propagated. |
|
Security |
Visitor Entitlement Policy Definitions |
Note: Definitions that you create using your own custom code (APIs) are not propagated. |
|
Security |
Delegated Administration Policy Definitions |
Note: Only the roles that are required (that a given asset depends upon) are propagated. These delegated administration policies are propagated:
|
|
Security |
Delegated Administration and Visitor Entitlement Roles |
Note: Only the roles that are required (that a given asset depends upon) are propagated. Note: Roles that you create using your own custom code (APIs) are not propagated. Note: 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. |
|
Security |
Users |
Not propagated; the hashed passwords cannot be propagated. |
|
Security |
Groups |
Not propagated. |
|
WSRP |
WSRP Registration Data Remote portlets |
For more information on WSRP propagation, see Section 6.11, "Federated Portal (WSRP) Propagation." |
|
Content Management |
All Content Management information, items, types, metadata, and folders |
Propagation will not move the checkout status (if a user has an item checked out in staging, the user will not have it checked out in production after propagation). In a managed repository, a node that is published on the source will be in the "Draft" state when propagation adds it to the destination. Note: Workflows are not propagated. |
Security information consists generally of authentication data and authorization data. As Table 6-2 shows, authorization data consists of roles and policies, while authentication consists of users and groups.
Table 6-2 Types of Security Data
| Category | Data | Notes |
|---|---|---|
|
Authorization: Roles |
|
Stored in internal providers or external providers, such as a custom Authorization provider. |
|
Authorization: Policies |
|
N/A |
|
Authentication |
|
Stored in internal providers or external providers, such as an RDBMS user store or an OpenLDAP. Also stored in provider configurations and audit trails. |
Users and groups are never propagated by the propagation tools. In addition to user and group information, the propagation tools do 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 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 Section 6.2.7, "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.
You can think of a WebLogic Portal inventory as a large tree structure, with multiple levels of parent and child nodes. Each node in the tree represents the inventory for a part of the portal application. If a node is declared to be in scope, then that node and all of its descendents are in scope. That is, they will be included in the exported inventory file.
This section includes these topics:
If you do not want to propagate an entire portal application, you can use scoping to limit the propagated assets. The most common use cases for scoping include:
propagating only a content repository
propagating part of a content repository, such as the contents of a folder
propagating one or more specified desktops
The Oracle Enterprise Pack for Eclipse based propagation tools and the propagation Ant tasks both support scoping. The Oracle Enterprise Pack for Eclipse propagation tools let you manually make scoping decisions by selecting and unselecting nodes in the merged inventory tree. The Ant tasks let you control scoping with a scope.properties file that specifies which portal items are considered to be in scope.
Note:
It's important to remember that scope defines which portal artifacts will be included in a propagation. By default, scope is set to the entire Enterprise application, including content repository data. When you specify scope either manually or in a properties file, you are specifying what to include. If you specify a single desktop, for instance, only that desktop and its contents (books, pages, and so on) are propagated. Any other desktops in the portal, content, and other items are not propagated. If you limit the scope to a single content folder, then that folder, its contents, and its parent folders are propagated; however, the contents of parent folders are not propagated.
Performance is the primary use case for scoping. Because a scoped inventory reduces the overall size of an exported WebLogic Portal inventory, propagation tasks typically run faster. If you have a large content repository, you might not want to export it when you propagate a portal. In this case, you can move the content repository, and all of its content, out of scope.
Another reason to scope is security-related. You may want to exclude certain sensitive content from an inventory if you plan to transport that inventory through insecure channels.
The primary risk associated with scoping is that a scoped inventory file can include assets with dependencies that cannot be resolved. When an inventory is scoped, entire nodes (and descendants of the nodes) are excluded from the inventory. As a result, if included artifacts depend on excluded artifacts, those dependencies cannot be resolved. Typically out of scope dependencies are reported as manual elections. By default the propagation servlet will fail on manual add elections.
Tip:
If you want to exclude specific nodes from an inventory, we recommend that you use policies instead of scoping. Policies are explained in Section 6.6, "Using Policies."
The following are best practices if you intend to consider scoping an inventory:
If you want to selectively remove parts of a portal from an exported inventory, use scoping rather than policies.
Scope to the highest level possible. This ensures the that the destination environment will closely mirror the source environment. If you scope to a lower level, such as a specific desktop, additional quality assurance testing may be required on the destination.
If at all possible, avoid using scoping on an inventory file that has already been exported. It is preferable to use scoping only when you are extracting an inventory, such as with the Ant task OnlineDownloadTask.
Use scoping to exclude content repository data from an exported inventory, while including portal data.
Use scoping to exclude portal data from an exported inventory, but include content repository data.
You can set the scope of a propagation in the Oracle Enterprise Pack for Eclipse based propagation tools and in the Ant tasks.
This section includes these topics:
This section explains how to set scope using the New Propagation Session Wizard.
Tip:
For detailed information on using the propagation tools, see Chapter 7, "Using Oracle Enterprise Pack for Eclipse Propagation Tools."
When you create a new Propagation Session, you select a source and a destination inventory to merge. Before the merge, however, you are given the chance to make scoping decisions in the Select Global Scope dialog, shown in Figure 6-2. As shown in the figure, when you select a node to be in scope, the node's ancestors are automatically selected.
Note:
It is important to remember that when you select items in the Select Global Scope dialog, you are selecting items to be in scope. All other items in the enterprise application will be out of the scope of the propagation. Therefore, in Figure 6-2, only the selected shell definition and its ancestors will be propagated. For example, a content item's parent folder is included, but content types on which the content item depend are not automatically included.
To make selections in the Select Global Scope dialog, you must first select the Limit the scope to the specified nodes checkbox.
You can use the OnlineDownloadTask to scope an inventory file. This task takes a scope.properties file attribute. You can edit this file to include the items you want to include in the inventory file. If you do not specify a scope.properties file, then the entire enterprise application is considered to be in scope. For detailed information on the OnlineDownloadTask and other propagation Ant tasks, see Chapter 9, "Propagation Ant Task Reference."
WebLogic Portal gives you a great deal of freedom to scope your portal inventories. When you select an inventory node to be in or out of scope, that choice usually affects other nodes that are either dependent on or a dependent of the selected node. WebLogic Portal automatically determines these dependencies. In Oracle Enterprise Pack for Eclipse, you can see the dependencies visually: when you select a node, other related nodes are automatically selected.
This section helps you to understand the effects of four kinds of scoping decisions:
Section 6.5.6.1, "Scoping to the Enterprise Application Level" (the default)
Section 6.5.6.4, "Scoping to a Content Folder"
Note:
When you deploy the EAR file to a server in development mode, datasync data and some portal framework data is automatically extracted and placed in the database. If you intended to exclude some or all of the datasync data with scoping, then you will find that it is added automatically by the EAR deployment, effectively negating the scoping intention.
By default, all propagations are scoped to the Enterprise application level. This means that all of the artifacts that make up the portal that can be propagated are propagated. By default, the entire Enterprise application is in scope, as Figure 6-3 illustrates.
Figure 6-3 Scoping at the Enterprise Application Level
There are no preset scoping levels. Both the propagation tools and Ant tasks let you specify scoping however you want. The Ant tasks let you specify a scope.properties file, in which you specify which artifacts to propagate. (See also Section 8.6.3, "Understanding a Scope Property File.")
There are four major categories of portal artifacts that you can scope to:
Content Service – Includes content repositories, folders, content, types, and entitlements.
Personalization Service – Includes datasync data, such as campaigns, content selectors, and events.
Portal Framework – Includes portals, desktops, books, pages, and so on.
Security – Includes delegated admin roles and policies, visitor roles, global roles, security providers, and others.
Each of these top-level nodes are represented in the New Propagation Session wizard's Select Global Scope dialog, as shown in Figure 6-4. Using this dialog, you can drill into one of the top-level categories to refine the level of scoping. However, as previously noted, the best practice is to scope only to one of the top-level categories, such as the Content Service.
One of the most common scoping use cases is scoping to the desktop level. This means that you identify one or more specific desktops to be in scope. The rest of the enterprise application is then considered to be out of scope and is not propagated. As Figure 6-5 illustrates, when you scope to Desktop_1, the desktop and its children (books, pages, and so on) are placed in scope. Any other desktops and the rest of the Enterprise application are then out of scope. See Section 6.5.3, "What are the Risks of Scoping?" for information on the risks of scoping at this level.
Another common use case it scoping to a repository. When you scope to a repository, the entire repository is propagated, including all types, folders, and content, as illustrated in Figure 6-6. Any other repositories are not propagated, and no other part of the Enterprise application is propagated.
When you scope to a folder in a content repository, that folder, its contents, and all of the folder's parent folders are propagated. Note that the contents of parent folders are not propagated, only the parent folders themselves, as illustrated in Figure 6-7. See Section 6.5.3, "What are the Risks of Scoping?" for information on the risks of scoping at this level.
When you propagate portal assets, such as desktops containing pages and books, new pages and books are added to the Portal Library if they do not already exist there.
The WebLogic Portal Administration Console 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.
The following text describes the relationships between the following instances of portal assets:
Primary instance – Created in Oracle Enterprise Pack for Eclipse and stored in a .portal or .portlet file
Library instance – Created or updated in the WebLogic Portal Administration Console, and displayed in the Portal Resources tree under the Library node
Desktop instance – Created or updated in the WebLogic Portal Administration Console, and displayed in the Portal Resources tree under the Portals node
Visitor instance – Created or updated in the Visitor Tools
When you create a new desktop using the WebLogic Portal Administration Console, 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 Oracle Enterprise Pack for Eclipse. (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 WebLogic Portal Administration Console. 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 instance. On the other hand, a change to the desktop instance 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.
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 WebLogic Portal Administration Console. When a portal is propagated, any assets that are decoupled in the source application will remain decoupled in the destination.
For more details on the specific data propagated, see Section 6.3, "Propagation Reference Table."
Policies let you control how source and destination inventories are merged into a final inventory file. This section describes policies and presents examples to help you understand how to apply them.
This section includes the following topics:
Policies let you specify how to handle the following three merge cases:
Additions – If an asset exists in the source inventory, but not in the destination inventory, add it to the destination.
Deletions – If an asset exists in the destination inventory, but not in the source inventory, delete it from the destination.
Updates – If an asset exists in the source inventory and in the destination inventory, update the destination with the artifact in the source inventory.
Through the propagation tools, you can set two kinds of policies:
Global – Global policies apply to all assets in the source inventory. During a merge, each artifact in the source inventory is evaluated with respect to the destination inventory. The global policies dictate the outcome of each evaluation.
Local – Local policies apply to specific desktop and content management assets and override global policies for those assets. You can elect to apply a local policy to any desktop or content management asset in the source inventory. During a merge, the local policy overrides the global policy for that asset.
Figure 6-8 illustrates a simple, but common, example. In this case, the default global policies define how two inventories are merged. Portlets 2 and 3 on Desktop A are added to the destination's Desktop A. Portlet 5 from Desktop B is also added. However, Portlet 6 on the destination is deleted, because it did not exist in Desktop B on source system.
Tip:
By default global policies are set to accept adds, deletes, and updates.
Figure 6-9 shows the same source and destination system; however, in this case the global policy specifies that adds are ignored. In this case, Portlet 6 is removed from the destination desktop because it did not exist in the source desktop. None of the additional portlets from the source are added, because the global policy specifies that adds are to be ignored.
Figure 6-9 Ignoring Adds and Accepting Deletes
Figure 6-10 shows how a local policy overrides a global policy. In this example, the global policy is to accept adds; however, a local policy is placed on Portlet 1 in Desktop A. The local policy states that the portlet should be deleted from the destination. In this case, Portlet 1 on Desktop A is not propagated. The local policy overrides the global policy.
Figure 6-10 Local Policy Overrides Global Policy
In WebLogic Portal, multiple desktops can contain instances of the same library object, such as a portlet.
Tip:
It is important to understand the difference between a library instance and a desktop instance of an artifact, such as a portlet. For a detailed summary of this difference, see Section 6.5.7, "Scope and Library Inheritance" and Section 11.3.2, "Export and Import Scope."
Because global policies can be overridden at the desktop level, it is possible that the policies for instances of the same library object (such as a portlet) might conflict. The propagation software resolves these conflicts as follows:
Adds and Deletes – If after the application of global and local policies, any in-scope desktop requires a specific library object, then the library object will be included in the propagation.
Updates – If after the application of global and local policies any in-scope desktop requires a specific library object, then that library object will be updated during the propagation.
For example, consider this scenario: A user adds Page 1 to Book 2 on the source system, but another user adds the same Page 1 to Book 3 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 tools resolve the conflict by adding Page 1 to Book 2, and removing it in Book 3 on the destination system.
For another example, consider the following scenario:
Desktops A and B both include instances of Portlet X.
The global policy is set to accept adds.
A local policy to ignore adds is set on Desktop A.
There are no local policies set on Desktop B.
In this scenario, illustrated in Figure 6-11, there is a conflict between the local policy for Desktop A and the global policy inherited by Desktop B with respect to additions. Because Desktop B includes Portlet X, Portlet X is required in the propagation of Desktop B (Desktop B cannot be propagated properly without this portlet). Therefore, according to the rules stated previously, the library object for Portlet X will be included in the propagation, despite the policy override applied to Desktop A indicating that adds should be ignored.
Figure 6-11 Local Policies and Library Instances
When a propagation conflict is resolved by a propagation Ant task, the resolutions are listed in the log file that is created during processing. The Oracle Enterprise Pack for Eclipse based interface lists any changes that occurred in order to resolve conflicts in the Console view.
For information on log files, see Section 6.9, "Reviewing Log Files."
The basic propagation process starts with a source inventory and a destination inventory. You then merge these two files into a merged inventory file using either Oracle Enterprise Pack for Eclipse or the propagation Ant tasks.
Before you generate and commit a final inventory file, you have an opportunity to examine the pending changes that will be made to the destination server. You can view these changes in the following ways:
In a Oracle Enterprise Pack for Eclipse propagation session, click the Merged tab in the editor. This tab displays the merged inventory and highlights assets that represent additions, deletions, and updates. In addition, you can make last-minute changes to the inventory by selecting or deselecting specific nodes in the inventory tree. For more information on Section 7.6, "Viewing and Tuning the Merged Inventory."
If you are using the Ant tasks, you can examine a change manifest file. This file is an XML file that lists the adds, deletes, and updates that will be applied when the final inventory is generated. The OfflineExtractTask can extract the change manifest file from a merged inventory file. For details on these tasks, see Chapter 9, "Propagation Ant Task Reference."
User customizations refer to changes a user makes to his or her own desktop settings. 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. For this reason, user customizations are not propagated.
User customizations are preserved on the destination system, but when you propagate to a destination system, those customizations might be removed or modified on the destination server under certain conditions. For instance, an administrator might make changes through the WebLogic Portal Administration Console 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.
Tip:
It is a good practice to always review the verbose log after every propagation to ensure that all of your propagation elections were processed and to review the server log to check for propagation errors.
Propagation operations and tasks generate log messages in the following locations:
The server log.
The verbose log for the propagation application. This is the log file generated by the propagation servlet. This log file contains debug-level information. For information on enabling, disabling and configuring the verbose log file, see Section 6.13, "Configuring the Propagation Servlet."
Log files specified in the parameters of individual propagation Ant tasks. See Chapter 9, "Propagation Ant Task Reference" for detailed information on the Ant tasks.
You can enable verbose logging for the propagation tools in Oracle Enterprise Pack for Eclipse. This is the log file generated by the Oracle Enterprise Pack for Eclipse propagation tool. It contains debug-level information. For more information, see Section 7.9, "Enabling Verbose Logging."
The propagation tools are not transactional, and therefore do not support roll-back capability. If you must revert to a pre-propagated environment, use the backups that you created before beginning the propagation process. For more information, see Section 6.2.2, "Perform a Data Backup."
This section discusses propagation of federated portals.
Tip:
If you are upgrading to WebLogic Portal 10.2 or later versions, it is recommended that you read the section on upgrading federated portals in the Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Portal before reading this section.
This section includes these topics:
Section 6.11.3, "Editing Producer Registration Properties Using the Propagation Tool"
Section 6.11.4, "If Only Producer(s) are Upgraded to WebLogic Portal 10.2 or Later Versions"
WebLogic Portal 10.2 and later versions support features of WSRP 2.0 that permit a more flexible and practical approach to propagation of federated portals. With WebLogic Portal 10.2 and later versions, the consumer applications in staging and production environments can point to separate producers. The primary advantage of this new capability is that you can create and modify remote (proxy) portlets in a staging environment in isolation from the production environment.
Before version 10.0, if you wanted to propagate WSRP consumer applications, the consumers on the source and destination systems had to point to the same producer. This configuration, which is described in detail in "WSRP Propagation" in the WebLogic Portal 9.2 Production Operations Guide, included several limitations. For detailed information on using WSRP with WebLogic Portal, see the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.
If both the producer and consumer applications are at WebLogic Portal 10.2 or later versions (either new installations or upgrades), then propagation of consumers is fully supported. There is no requirement for the staging and production consumers to point to the same producer. This recommended configuration is illustrated in Figure 6-12. For detailed information on upgrading federated portals to WebLogic Portal 10.2 or later versions, see the Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Portal.
The procedure for propagating a federated portal where both the producer and consumer applications have been upgraded to WebLogic Portal 10.2 or a later version is:
Note:
The following steps apply whether or not the producer required the consumer to register itself.
Before propagating, add the producer to the consumer application on the destination system. For information on adding a producer, refer to the WebLogic Portal Administration Console online help. If the producer requires registration, you must perform the necessary registration steps. The producer handle you select must match the handle that was used to register the producer in the source system.
For example, if you added or registered the producer with the consumer in staging with the producer handle myProducer, you must also use myProducer as the producer handle in the production area.
Note:
You only need to perform Step 1 the first time you propagate the portal.
Propagate the producers (see number 2 in Figure 6-12). You must propagate to the destination system any new portlets that were deployed on any producers in the staging environment if those portlets are being accessed by consumers.
Note:
You also need to perform Step 2 if you made any changes to the portlet definitions on the producers.
Propagate the consumer portal application(s) from the source system to the destination system (see number 3 in Figure 6-12).
Figure 6-12 Recommended Configuration: Consumers Point to Separate Producers
When the propagation is completed, the consumer portal in the production environment is functionally equivalent to the consumer portal in the staging environment.
Note:
If you do not upgrade all producers and consumers to WebLogic Portal 10.3.x, then the configuration where consumers point to separate producers (Figure 6-12) is not supported. For detailed information on upgrading federated portals to WebLogic Portal 10.2 or later versions, see the Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Portal.
If you propagate a producer application, you have an option to edit the WSDL URL and registration properties of the target producer before you perform the propagation.
Note:
The primary use case for this feature is when you are developing producer and consumer applications in concert. In this scenario, in the development environment, the portal consumer application points to a development producer. In the staging environment, the staging consumer points to a staging producer, and so on. This scenario is illustrated in Figure 6-12. If you only propagate the consumer, it will continue to point to the same producer after propagation. In that case, you would not need to perform the steps in this section.
You can perform this editing operation in the propagation tool in the IDE as follows:
In the Merged Inventory view, select the WSRP Producer node, as shown in Figure 6-13.
Figure 6-13 Selecting the Producer Registration Node
In the Properties view, edit the properties in the Producer Registration section. These properties are:
Producer WSDL URL – Enter the WSDL URL of the target producer application. For information on the WSDL URL, see the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.
Registration Properties – Click the button provided to bring up the Producer Registration Properties dialog, as shown in Figure 6-13. You can remove a property or change its value; however, you cannot add a property or change its type. If you want to change add a property or change its type, you can do that by editing the wsrp-producer-registry.xml file. For detailed information on this file and registration properties, see "Storing Registration Properties" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.
Figure 6-14 Producer Registration Properties Dialog
The following steps are mandatory if you have upgraded a producer to WebLogic Portal 10.2 or later versions, but consumers(s) are not upgraded:
Obtain the producer registration handles from each consumer application. To do this, run the List Producers JSP utility as described in Section 6.11.6, "Listing Producer Handles."
Update the producer registration handles for each upgraded producer application. To do this, run the Update Registrations JSP utility as described in Section 6.11.7, "Updating Producer Registration Handles."
Propagate the consumer application(s).
If you upgrade only the consumer(s) to 10.2 or a later version, you are required to use the propagation model described in WSRP Propagation in the WebLogic Portal 9.2 Production Operations Guide. In this model, consumer applications in both staging and production environments must point to the same producer.
Note:
You only need to run the utility described in this section on the systems where your consumer applications are deployed.
This section explains how to run the List Producer JSP utility (listProducers.jsp) on both the staging and production systems on which your consumer applications are deployed. This utility obtains the registration handles for producers that have been previously added to your consumers.
Note:
You must have administration privileges to run the JSPs.
Note:
If your consumer application is deployed in a WebLogic Portal 9.2 or 8.1.5 (or later) environment, you must perform steps 1 and 2 below. If your consumer environment was already upgraded to WebLogic Portal 10.2 or a later version, steps 1 and 2 are not required.
This step is only required if your consumer application is deployed in a WebLogic Portal 9.2 or 8.1.5 (or later) environment. Extract the listProducers.jsp file from the following J2EE Shared Library. You can use an archive tool, such as WinZip, to extract the listProducers.jsp file from the archive:
<WLPORTAL_HOME>/propagation/lib/j2ee-modules/wlp-propagation-web-lib.war
This step is only required if your consumer application is deployed in a WebLogic Portal 9.2 or 8.1.5 (or later) environment. Copy the listProducers.jsp file you extracted into the web applications in which your consumers are deployed. Do this on both the staging and production systems.
Run the List Producers JSP utility on the staging or source system. For a 10.2 or later version installation, open a browser and enter the following URL:
http://host:port/EarProjectNamePropagation/wsrp/listProducers.jsp
Where EarProjectName is the name of the enterprise application deployed to the server. For example:
http://localhost:7001/myEarPropagation/wsrp/listProducers.jsp
For a 9.2 or 8.1.5 (or later) installation, the URL depends on where you placed the JSP. For example:
http://host:port/EarProjectNamePropagation/mydir/listProducers.jsp
When prompted, enter the correct user name and password for the server.
In the List Producers JSP, select the name of a consumer web application in the source system.
Click Submit Query. The JSP returns a table that lists the producer handle, WSDL, and registration handle for each producer that was added to the consumer.
Print or copy the information in this table. You will need this information to complete the steps in the next section, Section 6.11.7, "Updating Producer Registration Handles."
Repeat these steps on the production/destination system.
Note:
You only need to run the utility described in this section on the systems where your producer application is deployed.
This section explains how to run the Update Registrations JSP utility (updateRegistrations.jsp) on both the staging and production systems. This utility updates the registration handles for each consumer application the currently references a given producer.
Note:
If your producer application is deployed in a WebLogic Portal 9.2 or 8.1.5 (or later) environment, you must perform steps 1 and 2 below. If your producer environment was already upgraded to WebLogic Portal 10.2 or a later version, steps 1 and 2 are not required.
This step is only required if your producer application is deployed in a WebLogic 9.2 or 8.1.5 (or later) environment. Extract the updateRegistrations.jsp file from the following J2EE Shared Library. You can use an archive tool, such as WinZip, to extract the updateRegistrations.jsp file from the archive:
<WLPORTAL_HOME>/propagation/lib/j2ee-modules/wlp-propagation-web-lib.war
This step is only required if your producer application is deployed in a WebLogic 9.2 or 8.1.5 (or later) environment. Copy the updateRegistrations.jsp file you extracted into the web application in which your producer is deployed. Do this on both the staging and production systems.
On the destination system, run the Update Registrations JSP. To do this, To do this, open a browser and enter the following URL:
http://host:port/EarProjectNamePropagation/wsrp/updateRegistrations.jsp
Where EarProjectName is the name of the enterprise application deployed to the server. For example:
http://localhost:7001/myEarPropagation/wsrp/updateRegistrations.jsp
When prompted, enter the correct user name and password for the server.
In the JSP, enter the source and corresponding destination registration handles that you obtained from the consumer applications by running the List Producers utility described previously in Section 6.11.6, "Listing Producer Handles."
Click Submit.
Repeat this procedure for each consumer involved in the propagation that is registered with the producer.
Note:
The Update Registrations JSP copies registrations so that both consumers have access to the remote portlet.
The propagation management servlet has a configuration setting to help mitigate "denial of service" attacks. The servlet is configured with a maximum size allowed for uploaded files (files uploaded over HTTP). By default, this is set to 10 megabytes. If any given file inside the inventory ZIP file is larger than this value, it will be rejected. This section explains how to either work around this limitation or change the propagation servlet's configuration to allow larger files.
The simplest workaround to this file size limit is to physically copy your file, through FTP or another means, from the source to the destination server. After you copy the file to the destination, you can use the OnlineUploadTask's readFromServerFileSystem attribute to perform the upload. For information on this task, see Section 9.1.6, "OnlineUploadTask."
You can override the 10 megabyte default file upload limit using a deployment plan. A deployment plan is an optional XML file that configures an application for deployment to WebLogic Server. A deployment plan works by setting property values that would normally be defined in the WebLogic Server deployment descriptors, or by overriding context parameter values already defined in a WebLogic Server deployment descriptor.
Tip:
The creation and use of deployment plans is thoroughly discussed in the WebLogic Server documentation. For more information, see "Configuring Applications for Production Deployment" and "Redeploying Applications in a Production Environment" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
To modify the file size limit using a deployment plan, follow these steps:
Create a deployment plan file. There are several ways to create a deployment plan, as discussed in the WebLogic Server documentation. Example 6-1 shows a sample deployment plan configured to modify the propagation web application.
Tip:
The location of the deployment plan must be specified in your domain's config.xml file. A sample stanza is shown in Example 6-2. Refer to the WebLogic Server documentation for more information.
Add <variable-definition> and <variable-assignment> elements to change the context deployment descriptor parameter maximum_inventoryfile_upload_size. These elements are highlighted in bold type in Example 6-1. In the example, the upload file size limit is changed to 13 MB. Note that the overridden descriptor is associated with the application's web.xml file.
Example 6-1 Sample Deployment Plan
<deployment-plan xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <application-name>drtApp</application-name> <variable-definition> <variable> <name>CHANGEUPLOAD</name> <value>13000000</value> </variable> </variable-definition> <module-override> <module-name>propagation.war</module-name> <module-type>war</module-type> <module-descriptor external="false"> <root-element>weblogic-web-app</root-element> <uri>WEB-INF/weblogic.xml</uri> </module-descriptor> <module-descriptor external="false"> <root-element>web-app</root-element> <uri>WEB-INF/web.xml</uri> <variable-assignment> <name>CHANGEUPLOAD</name> <xpath>/web-app/context-param/ [param-name="maximum_inventoryfile_upload_size"]/param-value</xpath> </variable-assignment> </module-descriptor> </module-override> </deployment-plan>
Example 6-2 Deployment Plan Location in Sample config.xml
<app-deployment>
<name>drtApp</name>
<target>portalServer</target>
<module-type>ear</module-type>
<source-path>/myProject/myApplication</source-path>
<deployment-order>101</deployment-order>
<plan-dir>/myProject/applications/plan</plan-dir>
<plan-path>plan.xml</plan-path>
<security-dd-model>Advanced</security-dd-model>
</app-deployment>
Redeploy the application, as described in the WebLogic Server document, "Redeploying Applications in a Production Environment" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
Note:
This method is not recommended.
You can configure the file upload size directly in the propagation application's web.xml file. To modify this file, do the following:
Locate the propagation application's WAR file. This file is located in:
<WLPORTAL_HOME>/propagation/lib/j2ee-modules/wlp-propagation-web-lib.war
Unpack the WAR file and open the web.xml file for editing.
Add the stanza to the web.xml file shown in Example 6-3. In this example, the default file size is changed to 13 MB.
Repackage the WAR file.
Redeploy the application.
A number of configuration parameters that affect the propagation servlet are specified in the propagation web application's web.xml file. The preferred method for modifying these parameters is by using a deployment plan.
A deployment plan is an optional XML file that configures an application for deployment to WebLogic Server. A deployment plan works by setting property values that would normally be defined in the WebLogic Server deployment descriptors, or by overriding context parameter values already defined in a WebLogic Server deployment descriptor.
Tip:
The creation and use of deployment plans is thoroughly discussed in the WebLogic Server documentation. For more information, see "Configuring Applications for Production Deployment" and "Redeploying Applications in a Production Environment" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
Tip:
See also the section, Section 6.12, "Increasing the Default Upload File Size," for information on configuring the propagation servlet using a deployment plan.
The following sections show context parameters for the propagation application's web.xml file. To override these parameters, use a deployment plan. The parameters are used to set the following configurations:
The inventoryWorkingFolder parameter shown in Example 6-4 specifies a folder on the server where the propagation tools place certain runtime data, such as inventory exports. For detailed information on configuring the temporary space used on the server during propagation, see Section 6.14, "Configuring Temporary Space."
The example stanza shown in Example 6-5 is used to specify a short description to be placed in the export.properties file. This file contains summary information about the inventory; including who exported it, when it was exported, how many nodes are in the export, and other information.
The example stanza shown in Example 6-6 is used to enable or disable verbose logging.
The example stanza shown in Example 6-5 is used to specify the location of the verbose log file.
Note:
By default, this file is stored in a temporary directory in the domain. For detailed information on configuring the default temporary space used during propagation, see Section 6.14, "Configuring Temporary Space."
Certain propagation operations, such as creating an inventory file or combining two inventories, write temporary files to the file system. The temporary location where these files are written depends on the type of operation performed. This section explains how this temporary space is created and how to configure it.
Note:
The propagation tools do not typically remove these temporary files; therefore, they are available to help debug propagation problems. You may be required to clean up the temporary space at your discretion.
Online propagation operations take place on the server and include tasks such as uploading and committing inventories. (see Section 8.4, "Overview of Online Tasks"). Temporary space is created for online operations according to an algorithm where the first available of the following locations is used:
The value of the inventoryWorkingFolder context parameter, which is set in the propagation web application's web.xml file. See Section 6.13.1, "Configuring the Inventory Temporary Directory."
The servlet context attribute javax.servlet.context.tempdir. This temporary directory is required by the servlet specification. All servlet containers are responsible for creating this temporary space.
The system property java.io.tempdir.
Note:
Warning messages may appear in the propagation log files if the path to the temporary directory is longer than the operating system's path length threshold. This threshold varies among operating systems. The best way to avoid this problem is to make the path as short as possible.
Offline propagation operations take place outside the context of a server and include tasks such as combining and differencing inventories. (see Section 8.5, "Overview of Offline Tasks"). For offline operations, temporary space is specified by the Temporary space is created for offline operations system property java.io.tempdir.
Applications in development mode write datasync files to the file system. If you propagate to an application in development mode and datasync resources are marked to be deleted then be aware that the corresponding datasync files will be deleted from the file system. See Section 12.2, "Datasync Definition Usage During Development" for more information.
|
 Copyright © 2010, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|