| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.6) E14245-05 |
|
|
View PDF |
| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.6) E14245-05 |
|
|
View PDF |
This chapter includes tips and best practices for using the propagation tools. This chapter includes the following sections:
The following sections describe best practices to follow to achieve the most predictable and accurate results with the propagation tools. This section includes these topics:
Section 10.1.3, "Do Not Change Definition Labels and Instance Labels"
Section 10.1.4, "Do Not Manually Replicate Changes Between Environments"
Section 10.1.7, "Use Oracle Enterprise Pack for Eclipse to Develop a Propagation Process"
Section 10.1.9, "Avoid Propagating Across a Proxy Server or Load Balancer"
Section 10.1.10, "Ensure That the Cluster Administration Server is Running"
Section 10.1.12, "Restarting Export and OnlineCommit Operations"
Section 10.1.13, "Improving the Speed of the Online Operations"
Section 10.1.15, "Choosing the Inventory File Transport Protocol"
Section 10.1.17, "Ensure Appropriate Delegated Administration Rights"
Section 10.1.18, "Avoid LDAP and Database Synchronization Problems"
A common practice is to automate the propagation processes with a custom Ant script, as explained in Chapter 8, "Using the Propagation Ant Tasks."
Before beginning to write your own Ant script, be sure to review and consult the sample that has been provided. The sample contains a comprehensive set of steps for a propagation. You will likely need a reduced set to perform your propagation. Using the sample Ant script as a start is a good practice.
You may find the sample in the install at this location:
<WLPORTAL_HOME>/propagation/bin/propagation_ant.xml
Periodically download and retain a series of historical inventories for your environment. It is highly recommended that you place historical inventories in your source code control system (if size allows) or on a back-up disk drive (for very large inventories). We recommend that you automate a script to periodically take an inventory snapshot of the environment and store that inventory. The same care in maintaining historical versions of your code should be applied to inventories.
Note:
Inventory snapshots do not replace the need to perform database and file system backups.
When you create new portals and portal resources in Oracle Enterprise Pack for Eclipse, Oracle recommends that you change the definition labels and instance labels at that time to create meaningful names for these resources. After you have used the propagation tools to propagate changes between environments, it is very important that you do not change these resource labels. The propagation tools use definition labels and instance labels to identify differences between source and destination systems; inconsistent results might occur if you change these labels within Oracle Enterprise Pack for Eclipse or the Administration Console.
Tip:
Definition labels are described in the section "Portlet Properties in the Portlet Properties View" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal. Instance labels are described in the section "Portlet Properties in the Portal Properties View" in the same guide.
Create portal framework and security assets in only one environment. In other words, do not create an asset in staging and then manually create the same asset in production. If you make identical changes in both the source and target environment, the propagation tools cannot identify them as being the same changes—propagation is carried out as if they were two separate resources. This advice does not apply to datasync and content management assets; however, it is still a best practice to create assets in one environment only.
Choose the highest level of scoping for the propagation to ensure that the destination environment closely mirrors the source environment. If you scope to a lower level, such as web application or desktop, the source and destination systems 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 propagation tools 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 tools 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 Section 6.5.7, "Scope and Library Inheritance."
Tip:
An exception to this practice is using scope to include or exclude a content management system. A common practice is to propagate only the content management system or to propagate everything but the content management system.
The scoping and policy features offer powerful control over propagation. However, with this power can come some complexity. When first starting out with the propagation tools it is recommended that you retain the default scope (the full application) and the default Policy (accept all Adds, Updates, and Deletes). Once you are comfortable with the concepts and process of propagation, it is appropriate to start using the advanced features. For more information on scope, see Section 6.5, "Understanding Scope." For more information on policies, see Section 6.6, "Using Policies."
Oracle Enterprise Pack for Eclipse provides many features for defining how assets are to be propagated, including a user interface for visualizing the combined inventory. The Oracle Enterprise Pack for Eclipse interface is the best choice when propagating an application for the first few times from one environment to another. However, over time, the propagation process generally becomes routine with the same options chosen every time. The Ant tasks are more appropriate for supporting a repeatable process when the propagation scope and policy choices are well understood and held constant. For more information on using Oracle Enterprise Pack for Eclipse to propagation portals, see Chapter 7, "Using Oracle Enterprise Pack for Eclipse Propagation Tools." The Ant tasks are discussed in Chapter 8, "Using the Propagation Ant Tasks."
Oracle Enterprise Pack for Eclipse allows you to Import and Export inventories from running WebLogic Portal applications. However, Oracle Enterprise Pack for Eclipse does not provide access to all of the options available for these operations.
It is important to understand that Oracle Enterprise Pack for Eclipse is actually using the Ant tasks when invoking Import and Export. An Ant script is created and run whenever these features are used from Oracle Enterprise Pack for Eclipse. You can save the Ant script that is used by Oracle Enterprise Pack for Eclipse. By saving the script, you can examine it and begin to understand how it works. The OnlineDownload, OnlineUpload, and OnlineCommit tasks have numerous options that can be used when using the Ant tasks directly.
For information on saving propagation Ant scripts, refer to Oracle Enterprise Pack for Eclipse online help. For information on specific Ant tasks, see Chapter 9, "Propagation Ant Task Reference."
The Export Propagation Inventory to Server and Import Propagation Inventory From Server operations in Oracle Enterprise Pack for Eclipse, and the OnlineDownload, OnlineUpload, and OnlineCommit Ant tasks open an HTTP connection to a servlet designed to assist with the propagation. The servlet runs in the WebLogic Portal application running on WebLogic Server. The URL specified for these commands indicate how the servlet is addressed.
For WebLogic Portal applications deployed in a cluster, a proxy server or load balancer sits in front of the cluster to marshal traffic to the cluster nodes. While it is possible to target a propagation to the proxy, a better approach is to identify a single cluster managed node and to address it directly. This approach has these advantages:
The readFromServerFilesystem option for the OnlineUpload task can work reliably without a shared file system. See Section 9.1.6, "OnlineUploadTask."
Propagation verbose log files are stored only on the managed server that serviced the request. They will be easier to locate if the managed server is known. For information, see Section 6.13.4, "Specifying the Verbose Log File Location."
Propagation operations can take minutes to complete; the more network devices between the client and servlet increases the chances that communication will be disrupted.
The propagation tools primarily commit configuration changes into the WebLogic Portal application's database schema. Portal desktops, portlet preferences, content, and most other artifacts are persisted into the database. However, some security information such as entitlements and delegated administration policies are persisted into the embedded LDAP server intrinsic to every WebLogic Server instance.
In a cluster, the Administration Server is responsible for distributing updates to the embedded LDAP server to all nodes in the cluster. If the Administration Server is down, the nodes in the cluster can get out of sync if updates are made to entitlements or delegated administration. Therefore, it is strongly recommended to have the Administration Server running when the Propagation Tool is updating an application. This advice applies specifically to exporting a final inventory file to the server using Oracle Enterprise Pack for Eclipse (File > Export > Other > Propagation Inventory to Server), or a call to the OnlineCommit Ant task. See also Section 7.8, "Uploading the Final Inventory to the Server" and Section 9.1.2, "OnlineCommitTask."
Unlike any other activity in a WebLogic Portal application, the propagation tools iterate through the configuration of the entire WebLogic Portal application. Therefore, if there is a latent problem in the application configuration, the propagation tools are apt to encounter it. While these problems adversely affect the propagation, the true source of the error is usually at a deeper level.
To troubleshoot such a problem, attempt test the area in question using another means such as the WebLogic Portal Administration Console. This process can help you to discover and fix the actual problem or provide a simpler, reproducible test case.
Some cases have arisen where an unsupported database driver or corrupt security repository have negatively impacted the propagation tools. While these problems affect the propagation, the solution lies in addressing the root cause.
Note that during an Export Propagation Inventory to Server operation (Oracle Enterprise Pack for Eclipse) or OnlineCommit (Ant) operation, the propagation tools processes a list of changes to make on the destination system. At times, this list can be enormous, with thousands of necessary changes. This operation can take a significant amount of time. The propagation tools do not create an encompassing transaction for all changes for several reasons:
Performance concerns as the transaction grows larger and larger
Concerns for transaction deadlock in the database
The embedded LDAP repository is not transaction aware
During propagation, each change to the destination system is executed in its own transaction. If the propagation operation is interrupted in the middle, the configuration will be left in an incomplete state. For example, this situation can occur if the managed server hardware fails during the operation. In such a case, you can simply rerun the propagation tools. The tools will detect the new, shorter, list of remaining changes that need to be applied and will start again where the previous propagation failed.
The Export Propagation Inventory to Server and Import Propagation Inventory From Server operations in Oracle Enterprise Pack for Eclipse, and the OnlineDownload, OnlineUpload, and OnlineCommit Ant tasks are considered the online operations because they communicate with the propagation servlet running in the WebLogic Portal application. These operations read and write large amounts of database records while working with the WebLogic Portal application configuration. These operations are notable in that they tend to take the longest amounts of time to execute.
An effective way to improve the speed of these operations is to improve the performance of the database. Allocating more powerful hardware is an effective but expensive solution. Often, having a database administrator tune the database is effective.
The Microsoft Windows file system is more restrictive than those of other operating systems. Specifically, there are file path length limitations that are problematic when working with deeply nested folder structures.
The propagation tools make use of the file system extensively when doing certain operations. The tools use a designated working folder to write large numbers of files for the artifacts that they are exporting, importing, differencing, and committing. This ordinarily is not a problem because the propagation tools use the working folder judiciously and do not create deeply nested folders. However, if the working folder itself is set to be a deeply nested folder, the propagation tools may fail while trying to create, read, delete or update some of the files because the file path may exceed the limit.
By default, the propagation servlet will use the temporary folder provided by the WebLogic Server servlet container as the working folder. This path is a nested folder under the domain directory, like:
C:\bea100\user_projects\domains\wlpHome_domain\servers\AdminServer\ tmp\_WL_user\wlpBEA\c0b5ju\public
This path can grow very long, especially if the domain folder path is lengthy. In some cases, this will cause the propagation tools to fail because the file path exceeds the limit.
A best practice for Windows systems is to not allow the propagation servlet to use the servlet container temporary space for its working directory. Give the working folder a small folder path length, like C:\bea100\propagation. You can set the working folder in web.xml for the Propagation Tool web application, as described in Section 6.13, "Configuring the Propagation Servlet."
The Export Propagation Inventory to Server and Import Propagation Inventory From Server or OnlineDownload/OnlineUpload operations retrieve or push inventory files to a remote server that is hosting a WebLogic Portal application. Because these operations use a servlet, this transfer uses HTTP. When firewalls are an issue, this can be a convenient approach to move the inventory files. It is also the only approach supported by the Export Propagation Inventory to Server and Import Propagation Inventory From Server operations in Oracle Enterprise Pack for Eclipse.
To ensure that the Export Propagation Inventory to Server/OnlineUpload operation succeeds, it is sometimes necessary to increase the allowed upload size of the servlet. Because upload capabilities have historically been used in Denial of Service attacks on web applications, the default limit for any uploaded inventory is one megabyte. This can be increased in web.xml by following the instructions in Section 6.13, "Configuring the Propagation Servlet."
Additionally, the user must be granted upload rights in the WebLogic Server console. Only users in the Administrator and Deployer roles are granted this right by default. Other users can be given this right in the WebLogic Server Console. For more information see "Resource Types You Can Secure with Policies" in Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server.
If you want, you can use other approaches to move files to and from the destination, such as FTP, a source code control client, or a physical medium such as a DVD. In these cases, the OnlineDownload and OnlineUpload tasks support an option to avoid using HTTP for the file transfer. They allow the administrator to position the inventory file on the server's local file system, and reference the file location in the Ant task.
For example:
<target name="downloadProductionInventory">
<onlineDownload
servletURL="http://myhost/propagation/inventorymanagement"
username="weblogic" password="webl0gic" allowHttp="true"
outputInventoryFile="/opt/inventories/prod.zip"
outputToServerFileSystem="true"
/>
</target>
In this example, inventory file is not downloaded to the machine running the Ant task, rather, the file is written to the file system of the server machine, at location /opt/inventories/prod.zip.
The OnlineUpload task has a similar flag, called readFromServerFileSystem. For more information on these Ant tasks, see Chapter 9, "Propagation Ant Task Reference."
The propagation tools can commit nearly all of the changes to configuration artifacts that it detects. However, there are a few types of changes that the propagation tools can detect, but cannot automatically commit. These types of changes are called Manual Changes. The administrator must manually make these changes using the WebLogic Portal Administration Console or the WebLogic Server Console.
The following is a list of changes that are detected, but always manual:
Global roles
WLP content repository definitions
WSRP Producer registrations (if both consumer and producer applications are at WebLogic Portal 10.0 or greater, then no manual steps are required)
Any out of scope dependency
Portal framework markup files, such as .shell, .theme, and .portlet.
To view the required Manual Changes in the Oracle Enterprise Pack for Eclipse, right-click on the Merged Inventory view and filter for Manual Changes Only. When using the Ant tasks, the OfflineExtractTask produces a file that lists the Manual Changes.
Tip:
You can use the OfflineCheckManualElectionsTask to halt an automated propagation if any manual changes are detected. For information on this task, see Section 9.2.1, "OfflineCheckManualElectionsTask."
You must be a member of the PortalSystemAdministrators role to run any online propagation tool tasks. See Section 7.2, "Security and Propagation" for more information.
If the embedded LDAP repository and database become out of sync, it is possible that some policy data will be lost during propagation. To prevent this situation from occurring, the propagation tools automatically detect when LDAP and the database are out of sync and, by default, prevent download and commit operations. See Section 9.1.2, "OnlineCommitTask" and Section 9.1.3, "OnlineDownloadTask" for more information.
Possible reasons for these two stores to become out of sync are:
Resetting the database tables or changing to a new database schema without also resetting the embedded LDAP store.
Resetting the embedded LDAP store without also resetting the database tables.
Updating delegated administration or entitlement data via the WebLogic Portal Administration Console or propagation tools without a running the Administration Server.
To avoid the synchronization problem:
Understand and honor the coupling between the embedded LDAP store and database tables; do not reset one without the other.
Ensure the cluster Administration Server is running while doing propagations or manually administer delegated administration and entitlements.
This section contains a list of common problems that you might encounter while using the propagation tools. None of these issues represent product problems; typically they result from general misuse or misunderstanding of the propagation tools.
This section includes these topics:
Section 10.2.1, "Propagation Fails Trying to Add an Artifact Because the Artifact Already Exists"
Section 10.2.3, "Cannot Propagate Between Applications that do not have Identical J2EE Structures"
Symptom: Errors that appear on the console indicate that there are problems adding an artifact in some area of the inventory (Content, Portal, Security, etc.)
Cause: The user running the propagation has more delegated administration rights to the source application than the destination application. Because of this, the source inventory contains more artifacts than the destination inventory. The propagation tools therefore believe that those artifacts need to be added to the destination. Upon doing so, the Add operation fails because that artifact already exists in the destination.
Solution: Works as designed. In general, it is best to propagate with a user that has full delegated administration rights to an application. See Section 10.1.17, "Ensure Appropriate Delegated Administration Rights."
Symptom: Errors will appear on the console indicating that there are problems reading the uploaded inventory.
<Error> <InventoryServices> <000000> <FAILURE: There was no uploaded inventory in the request.>
<Error> <InventoryServices> <000000> <The files in the upload directory could not be read.>
Cause: WebLogic Server restricts the right to uploading files to a server to the Administrator and Deployer roles. This is a security mechanism.
Solution: Works as designed. The user running the propagation must be granted sufficient rights, such as the Administrator or Deployer roles, in the WebLogic Administration Console. See Resource Types You Can Secure with Policies" in Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server.
Symptom: Errors will appear on the console indicating nodes cannot be added because their parent does not exist. The parent is usually a web application name, or a resource that comes from files within the web application, like .portlet, .shell, .laf files.
Cause: The propagation tools assume that the EAR file that was used on the source system will be moved to the destination system and the core J2EE structure will not be modified by deployment plans. This includes maintaining the same name for the application, and context paths for all web applications.
Solution: Works as designed.
Symptom: Errors will appear on the console indicating that there are problems reading or writing InputStreams for content items.
<Error> <ContentManagement> <000000> <com.bea.content.RepositoryException: java.io.IOException: Stream closed at com.bea.content.internal.server.dao. DaoBase.doDatabaseAction(DaoBase.java:248) at com.bea.content.internal.server.dao. DaoBase.doExecuteActionAndCloseConnection(DaoBase.java:204)
Cause: This has only been seen by Oracle database users using an unsupported Oracle 9i Thin database driver.
Solution: Works as designed. Use a supported database driver, such as 10G Thin. See "Oracle Fusion Middleware Supported System Configurations."
|
 Copyright © 2010, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|