Production Operations Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using the Propagation Ant Tasks

The propagation Ant tasks provide a full set of tools that you can use to propagate WebLogic Portal assets from one environment to another programmatically.

This chapter introduces the propagation Ant tasks and discusses related topics such as scoping and policies. This chapter includes the following sections:

 


Introduction

The Ant tasks let you perform all of the functions that you can perform with the Workshop for WebLogic propagation tools, plus additional options and functions, such as placing the server into maintenance mode. The Ant tasks:

 


Before You Begin

Note: 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.

Before you attempt to propagate a portal web application using the Ant tasks described in this chapter, it is important to be familiar with the basic concepts of WebLogic Portal propagation. For detailed information on planning a propagation strategy, see Developing a Propagation Strategy. The Ant tasks provide the same basic features as the Workshop for WebLogic propagation tools. The basic concepts and considerations outlined in Propagation Topics apply to both the propagation tools and to the Ant tasks.

Tip: We also recommend that you read Using Workshop for WebLogic Propagation Tools before designing an Ant-based propagation script. This chapter describes how to propagate a portal using the Workshop for WebLogic propagation tools. These tools step you through the propagation process and provides a visual interface for merging, viewing, and tuning inventories. Reviewing and understanding the workflow used by the propagation tools can be useful to you as you plan your Ant-based propagation.

 


Installing the Ant Tasks

The Ant tasks are divided into two categories: online and offline. The online tasks interact with a WebLogic Portal application that is deployed and running. For example, the OnlineDownloadTask lets you extract a portal inventory from a live server and store it in a file. To accomplish this, the task communicates with a servlet that is deployed with the enterprise application. The online tasks are summarized in Overview of Online Tasks.

The offline tasks operate on inventory files that have already been extracted and saved. The offline tasks do not require network connectivity. The offline tasks are summarized in Overview of Offline Tasks.

To use either the online or offline Ant tasks, you need to put the JAR files containing the tasks in your CLASSPATH. To use the online tasks, you also need to deploy a library module with the Portal EAR Project on the source and destination systems.

This section includes these installation topics:

Required JAR Files

To run the propagation Ant tasks, you must place several JAR files in the CLASSPATH for the Ant tasks on the system where you intend to use them, as described in this section.

  1. Using a utility such as WinZip, open the following WAR file:
  2. BEA_HOME/weblogic92/portal/lib/modules/wlp-propagation-web-lib.war 
  3. Extract the following JAR files and save them on your system, and add them to the CLASSPATH for the Ant tasks on the system where you intend to use them:
    • p13n_prop.jar
    • netuix_prop.jar
    • content_prop.jar
  4. Also add the following JAR files to the CLASSPATH for the Ant tasks:
    • BEA_HOME/weblogic92/platform/lib/p13n/p13n_common.jar
    • BEA_HOME/weblogic92/common/p13n/lib/p13n_prop_ant.jar
  5. If you are running the Offline Tasks, you also need the following JARs:
    • BEA_HOME/weblogic92/server/lib/xbean.jar
    • BEA_HOME/weblogic92/server/lib/api.jar

Deploying the Propagation Servlet

A servlet that handles propagation requests is provided with your WebLogic Portal installation. If you intend to use the online Ant tasks, this servlet must be deployed in the Portal EAR Project that contains the portal application(s) you want to propagate.

By default, the Propagation Service facet is included in a Portal EAR Project, as shown in Figure 8-1. This facet includes the propagation servlet. If you created the Portal EAR Project with the Propagation Service facet selected, then the propagation servlet is automatically deployed when you deploy the EAR to the server.

Figure 8-1 Propagation Service Module

Propagation Service Module

When it is deployed, the name of the servlet is earProjectNamePropagation.

Where earProjectName is the name of the EAR project that contains the portal application that you are propagating. For example: myEARProjectPropagation

Tip: You can see that the servlet has been added to your application by looking in the application’s META-INF/weblogic-application.xml file. Listing 8-1 shows the stanzas added for the example application, myEarProject.
Listing 8-1 Propagation Servlet Configuration
<library-ref>
    <library-name>wlp-propagation-app-lib</library-name>
</library-ref>
<library-context-root-override>
    <context-root>propagation</context-root>
    <override-value>myEarProjectPropagation</override-value>
</library-context-root-override>

You need to know the name of the servlet when you use the online Ant tasks, because these tasks use the servlet to process their requests. For example, the OnlinePingTask takes a serverURL parameter that requires the servlet name:

servletURL="http://localhost:7001/myEarProjectPropagation/
inventorymanagement"

You can check whether the propagation servlet is included in your EAR project by doing the following:

  1. Open Workshop for WebLogic.
  2. Right-click the EAR project in the Package Explorer, and select Properties. The Project Facets dialog appears, as shown in Figure 8-2.
  3. Figure 8-2 Checking the Propagation Service Facet


    Checking the Propagation Service Facet

  4. In the Project Facets dialog, be sure that the Propagation Service facet is included. If it isn’t, select Add/Remove Project Facets and add this facet.
  5. Click OK to complete the operation.

Testing the Ant Installation

WebLogic Portal provides a sample Ant build script that you can use to execute each of the propagation Ant tasks. This section explains how to use the sample build script to test that the propagation servlet is installed correctly. The sample build script is:

BEA_HOME/weblogic92/portal/bin/propagation/propagation_ant.xml
  1. Start the WebLogic Portal server in which your portal EAR project is deployed.
  2. Edit the sample build script appropriately to include correct values for your WebLogic Portal installation directory, a directory in which to write script output, the propagation servlet URL, and other information.
Tip: The script file includes detailed information about the variables you need to provide. Be sure to read the instructions in the script carefully.
  1. After you have properly configured the build script variables, run the OnlinePingTask. To do this, enter the following command.
  2. ant -f propagation_ant.xml pingSrc

If the operation succeeds, you will see the output shown in Listing 8-2.

Listing 8-2 Successful Ping Message
pingSrc:
     [echo] ****** Start: pingSrc ******
[onlinePing] INFO: Using the logger delegate (com.bea.p13n.management.inventory.util.OfflineInventoryLoggerDelegate) specified in the propagation_context.properties file.
[onlinePing] WARNING: This command is using HTTP, which will transmit the administrator password in plain text. It is recommended to set allowHttp to false.
     [echo] ****** Finish: pingSrc ******
Tip: You can copy the propagation_ant.xml build script and use it as a basis for creating your own custom propagation build scripts. Note that the sample script includes examples of running each task both with and without a condition property. The condition property, provided by the Ant ConditionTask, allows you to implement simple flow control in the Ant script.

 


Overview of Online Tasks

The online tasks operate on a WebLogic Portal application that is deployed and running. They communicate with the portal application through a servlet that is deployed with the enterprise application. For example, online tasks let you create and download inventory files from the server to another machine. For information on the propagation servlet, see Deploying the Propagation Servlet.

Note: The online Ant tasks use HTTP or HTTPS to reach WebLogic Server, therefore you must make sure that the intervening firewalls allow that.

This section includes these topics:

Online Task Summary

Table 8-2 summarizes the online propagation Ant tasks.

Table 8-1 Online Tasks
OnlineCheckMutexTask
Verifies that the propagation servlet is not currently in use by another process.
OnlineCommitTask
Performs a final inventory file merge and commits the final merged inventory to the destination server.
OnlineDownloadTask
Downloads the inventory from a currently running WebLogic Portal application to a specified ZIP file.
OnlineMaintenanceModeTask
Prevents administrators from making changes to the portal through the WebLogic Portal Administration Console.
OnlinePingTask
Tests if the propagation management servlet is running on the designated server.
OnlineUploadTask
Uploads an inventory file to a temporary location associated with a running WebLogic Portal application.

Using Online Tasks with HTTPS

To use HTTPS with the online Ant tasks, follow the standard WebLogic SSL instructions found in the WebLogic Server document, “Configuring Identity and Trust.”

Note: When formatting the URL to the remote WebLogic server, be sure to specify the actual host name of the system rather than localhost if you are on the same system. Also, be sure to use the HTTPS port number for the server. The default is 7002.

Troubleshooting Online Tasks

If an online propagation Ant task fails, typically the failure is caused by one of these reasons:

 


Overview of Offline Tasks

Offline Ant tasks operate exclusively on previously exported inventory files. These tasks operate on a single inventory file or on two inventory files to explore and manipulate the contents of the inventor(ies). The offline tasks provide features similar to the Workshop for WebLogic propagation tools.

These tasks do not require connectivity to a live WebLogic Portal application. For instance, you can use offline tasks to combine and compare source and destination inventory files.

This section includes these topics:

Offline Task Summary

Table 8-2 lists the offline propagation Ant tasks.

Table 8-2 Offline Tasks
OfflineCombineTask
Combines src.zip and dest.zip into a new inventory, combined.zip.
OfflineDiffTask
Differences src.zip and dest.zip and writes the results to diff_cm.xml.
OfflineElectionAlgebraTask
Allows for algebraic operations on two change manifest files.
OfflineExtractTask
Extracts the working artifacts out of combined.zip for viewing.
OfflineInsertTask
Inserts updated working artifacts into combined.zip.
OfflineListPoliciesTask
Exports the valid policies from an inventory file.
OfflineListScopesTask
Lists the scopes in src.zip that will be used to combine two inventories.
OfflineSearchTask
Finds nodes with a specific string in their name, to help verify the wanted node was exported.
OfflineValidateTask
Makes sure combined.zip is a valid ZIP file.

Troubleshooting Offline Tasks

If an offline propagation Ant task fails, typically the failure is caused by one of these reasons:

 


Scoping an Inventory

Scoping refers to limiting the number of artifacts in an exported WebLogic Portal inventory, and, therefore, the number of artifacts that must be added, deleted, or updated during propagation. In general, scoping reduces both the duration and complexity of propagation operations.

Tip: Before continuing, we recommend you review the detailed discussion of scoping, in Understanding Scope.

This section includes these topics:

Scoping with Ant Tasks

Several of the Ant tasks either create or use a property file, by default called scope.properites, that specifies scoping rules.

For example, you can edit the scope.properties file to adjust the propagation scope and then use the file as a parameter to the OnlineDownloadTask. This file declares how the task is to treat each node in the inventory as either in scope or out of scope. The task looks at the scoping rules and applies them to the exported inventory. As a result, the scoped inventory file is usually a subset of the full inventory. For more information on the scope.properties file, see Understanding a Scope Property File.

Sample Scoping Workflow

This section explains the basic workflow for scoping an inventory using the Ant tasks. The objective of this workflow is to reduce the size and complexity of an inventory file through scoping. The result of this workflow is a scope.properties file. This file contains a set of scoping rules that you can then use when you combine two inventories to produce a final merged inventory.

The Ant tasks used in this workflow include:

Figure 8-3 illustrates the basic steps involved in scoping an inventory file. This procedure uses Ant tasks in a chain to produce the final output: a scope.properties file containing the scoping information needed to combine inventories.

Figure 8-3 Scoping a Source Inventory

Scoping a Source Inventory

The steps shown in Figure 8-3 include the following:

  1. Call the OnlineDownloadTask. The first time you call this task, do not specify the scopeFile attribute. If you do not specify this attribute, the task retrieves the entire inventory from the server. The retrieved inventory is stored in a ZIP file, which is shown in Figure 8-3 as fullInventory.zip.
  2. Use OfflineListScopesTask to extract a scope.properties file from the inventory file. The scope.properties file specifies the scoping rules that were used to produce the inventory. See Understanding a Scope Property File for more information on the contents of a scope.properties file. To produce a scoped inventory, edit the scope.properties file and use the edited file as input to the OnlineDownloadTask again.
  3. Run the OnlineDownloadTask again with the edited scope.properties file as input. The result of this operation is a new inventory file that only includes the artifacts that were within the specified scope.
  4. The final step in this workflow is optional. It is included in Figure 8-3 to show that you can extract the scope.properties file from the scoped inventory file. In fact, the properties file that is returned is identical to the one that was used as input to the OnlineDownloadTask in Step 3.

After you have obtained a scoped source inventory file, you can combine it with a destination inventory file to produce a merged inventory file.

Understanding a Scope Property File

Listing 8-3 shows the first nine lines of a scope.properties file. The file lists the parts of the application that are considered to be in scope. You can edit this file to remove assets that you do not want to propagate. For example, to remove all content repository assets from the propagation, you could remove lines labeled scope_2 through scope_8.

Listing 8-3 Excerpt from a scope.properties File
scope_0=Application
scope_1=Application\:ContentServices
scope_2=Application\:ContentServices\:Tools_Repository
scope_3=Application\:ContentServices\:Tools_Repository\:ContentNodes
scope_4=Application\:ContentServices\:Tools_Repository\:ContentTypes
scope_5=Application\:ContentServices\:Tools_Repository\:GlobalEntitlements
scope_6=Application\:ContentServices\:Tools_Repository\:GlobalDelegatedAdminPolicies
scope_7=Application\:ContentServices\:GlobalEntitlements
scope_8=Application\:ContentServices\:GlobalDelegatedAdminPolicies
scope_9=Application\:PersonalizationService
scope_10=Application\:PersonalizationService\:PlaceholderService

 


Using Policies

Policies let you control how source and destination inventories are merged when they are combined into a final inventory file. To use policies, export a policy.properties file using the OfflineListPoliciesTask. This task lets you set global policies to apply to all assets in the inventory. For example, you can elect to accept all additions, but reject deletions, and updates. See Understanding a Policies Property File. You can then edit the policy.properties file to modify the policy elections for specific assets, if you want to.

Tip: Before continuing, we recommend you review the detailed discussion of policies in Using Policies.

Policies let you elect how to handle the following three merge cases. Each merge case can be set to true or false in the policy file.

Understanding a Policies Property File

Listing 8-4 Shows an excerpt from a policies.properties file. As you can see, in every case, the policy for this propagation is to accept (Y) adds and deletes, but to ignore (N) updates. A policy is set on each asset of the portal. You can change the policy on an asset by editing this file.

Listing 8-4 Excerpt from a policies.properties File
policy_0_taxonomy=Application
policy_0_adds=Y
policy_0_updates=N
policy_0_deletes=Y
policy_1_taxonomy=Application:ContentServices
policy_1_adds=Y
policy_1_updates=N
policy_1_deletes=Y
policy_2_taxonomy=Application:ContentServices:Tools_Repository
policy_2_adds=Y
policy_2_updates=N
policy_2_deletes=Y
policy_3_taxonomy=Application:ContentServices:Tools_Repository:ContentNodes
policy_3_adds=Y
policy_3_updates=N
policy_3_deletes=Y
policy_4_taxonomy=Application:ContentServices:Tools_Repository:ContentTypes
policy_4_adds=Y
policy_4_updates=N
policy_4_deletes=Y
policy_5_taxonomy=Application:ContentServices:Tools_Repository:GlobalEntitlements
policy_5_adds=Y
policy_5_updates=N
policy_5_deletes=Y

 


Combining and Committing Inventories

You can think of propagation as a combining operation. When you propagate a portal, you combine the contents of a source inventory with a destination inventory. The combining is governed by scoping and policy rules. The previous section, Scoping an Inventory, explained how to create a scope.properties file, which contains the scoping rules for an inventory. You can use this file as input to the OfflineCombineTask, which uses scoping information to decide which artifacts to combine to produce the final inventory file.

This section explains the basic workflow for combining and committing inventories using propagation Ant tasks. The Ant tasks used in this workflow include:

Figure 8-4 shows the basic workflow for combining and committing inventories. The workflow assumes that you have already exported (using the OnlineDownloadTask) a source and a destination inventory file.

Figure 8-4 Combining and Committing an Inventory

Combining and Committing an Inventory

After you have a source and destination inventory file, you can combine them using the OfflineCombineTask. The result of this task is a combined inventory file. This file is a combination of the source and destination inventory files with scope and policy rules (if they were specified) applied.

Use the OnlineUploadTask to move the combined inventory to the destination server. Use the OnlineCommitTask to commit the combined inventory on the destination server.

The OfflineCombineTask, OnlineUploadTask, and OnlineCommitTask are explained in Propagation Ant Task Reference.


  Back to Top       Previous  Next