|
|
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:
A common practice is to automate the propagation processes with a custom Ant script, as explained in 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:
BEA_HOME/wlserver10.0/portal/bin/propagation/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 Workshop for WebLogic, BEA 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 Workshop for WebLogic or the Administration Console.
| Tip: | Definition labels are described in the section “Portlet Properties in the Portlet Properties View” in the Portlet Development Guide. 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 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 Understanding Scope. For more information on policies, see Using Policies.
Workshop for WebLogic provides many features for defining how assets are to be propagated, including a user interface for visualizing the combined inventory. The Workshop for WebLogic 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 Workshop for WebLogic to propagation portals, see Using Workshop for WebLogic Propagation Tools. The Ant tasks are discussed in Using the Propagation Ant Tasks.
Workshop for WebLogic allows you to Import and Export inventories from running WebLogic Portal applications. However, the Workshop for WebLogic does not provide access to all of the options available for these operations.
It is important to understand that the Workshop for WebLogic is actually using the Ant tasks when invoking Import and Export. An Ant script is created and run whenever these features are used from Workshop for WebLogic. You can save the Ant script that is used by Workshop for WebLogic. 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 Workshop for WebLogic online help. For information on specific Ant tasks, see Propagation Ant Task Reference.
The Export Propagation Inventory to Server and Import Propagation Inventory From Server operations in Workshop for WebLogic, 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:
readFromServerFilesystem option for the OnlineUpload task can work reliably without a shared file system. See OnlineUploadTask. 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 uploading a final inventory file to the server using Workshop for WebLogic, or a call to the OnlineCommit Ant task. See also Uploading the Final Inventory to the Server and 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 (Workshop for WebLogic) 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:
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 Workshop for WebLogic, 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 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 the Workshop for WebLogic.
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 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 the WebLogic Server document “Resource Types You Can Secure with Policies.”
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.
<target name="downloadProductionInventory">
<onlineDownload
servletURL="http://myhost/propagation/inventorymanagement"
username="weblogic” password="weblogic" 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 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:
To view the required Manual Changes in the Workshop for WebLogic, 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 OfflineCheckManualElectionsTask. |
You must be a member of the PortalSystemAdministrators role to run any online propagation tool tasks. These tasks include the online Ant tasks and the Export Propagation Inventory to Server and Import Propagation Inventory From Server operations in Workshop for WebLogic. However, unless you are also a member of the Administrators role, you will not be able to view or update any configuration artifacts in the WebLogic Portal application by default. You must be granted delegated administration rights to the artifacts you wish to propagate.
In most cases, it is recommended that you be a member of the Administrators role when you propagate. This allows you to propagate any artifact in the application and is the safest approach to propagation because the propagation tools have full visibility into the application configuration.
Note, however, that use cases exist in which the propagation is targeted to a specific area of the application and the previous advice does not apply. For example, a content administrator may want to propagate a single folder of content items. This user will likely not have delegated administration rights to any Portal Framework assets, but that is not a problem in this use case.
In such cases it is acceptable for you to perform a propagation without full delegated administration rights to the application. It is important to understand that this may cause errors in cases where the you are attempting to add items that exist in the destination, but are not visible to you because of the absence of delegated administration rights. You will see errors on the console about the conflicted artifacts failing to add because they already exist.
For more information on delegated administration, see the WebLogic Portal Security Guide.
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 OnlineCommitTask and OnlineDownloadTask for more information.
Possible reasons for these two stores to become out of sync are:
To avoid the synchronization problem:
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:
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 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.> |
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 the WebLogic Server document
“Resource Types You Can Secure with Policies.”
|
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 DaoBase.doDatabaseAction(DaoBase.java:248) DaoBase.doExecuteActionAndCloseConnection(DaoBase.java:204) |
Solution: Works as designed. Use a supported database driver, such as 10G Thin. See the following WebLogic Server document
“Supported Database Configurations.”
|
|