Skip Headers
Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal
10g Release 3 (10.3.2)

Part Number E14245-02
Go to Documentation Home
Go to Table of Contents
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

8 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 using Ant scripts.

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

8.1 Introduction

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

8.2 Before You Begin


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 Chapter 5, "Developing a Propagation Strategy." The Ant tasks provide the same basic features as the Oracle Enterprise Pack for Eclipse propagation tools. The basic concepts and considerations outlined in Chapter 6, "Propagation Topics" apply to both the propagation tools and to the Ant tasks.


We also recommend that you read Chapter 7, "Using Oracle Enterprise Pack for Eclipse Propagation Tools" before designing an Ant-based propagation script. This chapter describes how to propagate a portal using the Oracle Enterprise Pack for Eclipse 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.

8.3 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 Section 8.4, "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. Note that online tasks require a running server with the propagation servlet deployed; offline tasks to not. The offline tasks are summarized in Section 8.5, "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:

8.3.1 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

Description of Figure 8-1 follows
Description of "Figure 8-1 Propagation Service Module"

When it is deployed, you can access the servlet as follows:


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


You can see that the servlet has been added to your application by looking in the application's META-INF/weblogic-application.xml file. Example 8-0 shows the stanzas added for the example application, myEarProject.

Example 8-1 Propagation Servlet Configuration


You need to know the name of the propagation servlet when you use the online Ant tasks, because these tasks use the propagation servlet to process their requests. For example, the online tasks take a serverURL parameter that requires the propagation servlet address. The servlet address is as follows:


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

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

  1. Open Oracle Enterprise Pack for Eclipse.

  2. Right-click the EAR project in the Package Explorer, and select Properties. The Project Facets dialog appears.

  3. In the Project Facets dialog, be sure that the Propagation Service facet is included.

  4. Click OK to complete the operation.

8.3.2 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:

  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.


    The script file includes detailed information about the variables you need to provide. Be sure to read the instructions in the script carefully.
  3. After you have properly configured the build script variables, run the OnlinePingTask. To do this, enter the following command.

    ant -f propagation_ant.xml pingSrc

If the operation succeeds, the server was contacted successfully.


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.

8.3.3 Using the Ant Tasks Outside of a WebLogic Portal Environment

To use the online or offline Ant tasks outside of a WebLogic Portal environment, you need to copy a set of JAR files from a WebLogic Portal installation to your local environment. These JAR files must be placed in the CLASSPATH for the Ant tasks on the system where you intend to use them. Required JARS for Online Tasks

<WLPORTAL_HOME>/propagation/lib/netuix_prop.jar Required JARS for Offline Tasks


8.4 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 Section 8.3.1, "Deploying the Propagation Servlet."


The online Ant tasks use HTTP or HTTPS to contact the propagation servlet, therefore you must make sure that the intervening firewalls allow that.

This section includes these topics:

8.4.1 Online Task Summary

Table 8-1 summarizes the online propagation Ant tasks. See Chapter 9, "Propagation Ant Task Reference" for details on each task.

Table 8-1 Online Tasks

Task Description

Section 9.1.1, "OnlineCheckMutexTask"

Verifies that the propagation servlet is not currently in use by another process.

Section 9.1.2, "OnlineCommitTask"

Commits an inventory to a server.

Section 9.1.3, "OnlineDownloadTask"

Downloads the inventory from a currently running WebLogic Portal application to a specified ZIP file.

Section 9.1.4, "OnlineMaintenanceModeTask"

Prevents administrators from making changes to the portal through the WebLogic Portal Administration Console.

Section 9.1.5, "OnlinePingTask"

Tests if the propagation management servlet is running on the designated server.

Section 9.1.6, "OnlineUploadTask"

Uploads an inventory to a running server.

8.4.2 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" in Oracle Fusion Middleware Securing Oracle WebLogic Server.


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.

8.4.3 Troubleshooting Online Tasks

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

  • The server on which the source or destination portal application is deployed has not been started. Verify that the server or cluster has been started.

  • The propagation servlet is not deployed. Follow the instructions in Section 8.3.1, "Deploying the Propagation Servlet" to deploy the servlet.

  • There is a network problem. Use an operating system utility to make sure the server can be reached.

  • The propagation servlet is in use by another process. Only one thread can use the propagation servlet at one time. You can use the OnlineCheckMutexTask to check to see if another process is currently using the servlet.

8.5 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 Oracle Enterprise Pack for Eclipse propagation tools. See Chapter 9, "Propagation Ant Task Reference" for details on each task.

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

This section includes these topics:

8.5.1 Offline Task Summary

Table 8-2 lists the offline propagation Ant tasks.

Table 8-2 Offline Tasks

Task Description

Section 9.2.1, "OfflineCheckManualElectionsTask"

Tests for the presence of manual elections (changes).

Section 9.2.2, "OfflineCombineTask"

Combines and into a new inventory,

Section 9.2.3, "OfflineDiffTask"

Differences and and writes the results to diff_cm.xml.

Section 9.2.4, "OfflineElectionAlgebraTask"

Allows for algebraic operations on two change manifest files.

Section 9.2.5, "OfflineExtractTask"

Extracts the working artifacts out of for viewing.

Section 9.2.6, "OfflineInsertTask"

Inserts updated working artifacts into

Section 9.2.7, "OfflineListPoliciesTask"

Exports the valid policies from an inventory file.

Section 9.2.8, "OfflineListScopesTask"

Creates a list of all the taxonomies in an inventory.

Section 9.2.9, "OfflineSearchTask"

Finds nodes with a specific string in their name, to help verify the wanted node was exported.

Section 9.2.10, "OfflineValidateTask"

Makes sure is a valid ZIP file.

8.5.2 Troubleshooting Offline Tasks

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

  • The input parameters are not properly specified.

  • An unexpected error occurred, such as encountering a full disk.

  • A missing JAR file in the class path.

8.6 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.


Before continuing, we recommend you review the detailed discussion of scoping, in Section 6.5, "Understanding Scope."

This section includes these topics:

8.6.1 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 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 file, see Section 8.6.3, "Understanding a Scope Property File."

8.6.2 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 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:

  • OnlineDownloadTask – This task is used to retrieve an inventory file from a WebLogic Portal application that is running on a server.

  • OfflineListScopesTask – This task exports the valid scopes from an inventory file. You can specify the depth of the scope. The depth limits how far into the inventory tree the task traverses. This task produces a file, which you can edit.

  • OfflineExtractTask – This task exports files that are stored in the top level of an inventory ZIP file. One of these files is a file.

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

Figure 8-2 Scoping a Source Inventory

Description of Figure 8-2 follows
Description of "Figure 8-2 Scoping a Source Inventory "

The steps shown in Figure 8-2 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-2 as

  2. Use OfflineListScopesTask to extract a file from the inventory file. The file specifies the scoping rules that were used to produce the inventory. See Section 8.6.3, "Understanding a Scope Property File" for more information on the contents of a file. To produce a scoped inventory, edit the file and use the edited file as input to the OnlineDownloadTask again.

  3. Run the OnlineDownloadTask again with the edited 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-2 to show that you can extract the 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.

8.6.3 Understanding a Scope Property File

The taxonomies listed in a file indicate that the given taxonomy and all of its children will be included in the inventory. For example, Example 8-2 shows a one-line file, with only the taxonomy value Application specified. This taxonomy indicates that the entire application will be included in the inventory.

Example 8-2 Excerpt from a File


Example 8-3 is another simple scope file instruction, that indicates that all content from every repository associated with the application will be included in the inventory.

Example 8-3 Excerpt from a File


Example 8-4 indicates that only the content node node1 and its children and content type typeA and its children will be included.

Example 8-4 Excerpt from a File


In summary, the taxonomies listed in the previous examples have the following meanings:

  • Application is the root of all taxonomies and includes everything. If you scope to this taxonomy value, the entire application will be included in the inventory.

  • Includes all content from every repository.

  • Includes all content from the Tools_Repository content repository.

  • Includes all content nodes in the Tools_Repository content repository.

  • Includes node1 and all its children in the Tools_Repository content repository.

8.7 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 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 Section 8.7.1, "Understanding a Policies Property File." You can then edit the file to modify the policy elections for specific assets, if you want to.


Before continuing, we recommend you review the detailed discussion of policies in Section 6.6, "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.

8.7.1 Understanding a Policies Property File

Example 8-5 Shows an excerpt from a 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.

Example 8-5 Excerpt from a File


8.8 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, Section 8.6, "Scoping an Inventory," explained how to create a 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-3 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-3 Combining and Committing an Inventory

Description of Figure 8-3 follows
Description of "Figure 8-3 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.


The OnlineCombineTask performs the same function as exporting a propagation session to an inventory file with the propagation tool in Oracle Enterprise Pack for Eclipse. See Chapter 7, "Using Oracle Enterprise Pack for Eclipse Propagation Tools."

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 Chapter 9, "Propagation Ant Task Reference."