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:
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:
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. |
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:
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.
BEA_HOME/weblogic92/portal/lib/modules/wlp-propagation-web-lib.war
CLASSPATH
for the Ant tasks on the system where you intend to use them:CLASSPATH
for the Ant tasks: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.
When it is deployed, the name of the servlet is earProjectName
Propagation
.
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 . |
<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:
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
Tip: | The script file includes detailed information about the variables you need to provide. Be sure to read the instructions in the script carefully. |
If the operation succeeds, you will see the output shown in Listing 8-2.
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. |
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:
Table 8-2 summarizes the online propagation Ant tasks.
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. |
If an online propagation Ant task fails, typically the failure is caused by one of these reasons:
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:
Table 8-2 lists the offline propagation Ant tasks.
If an offline propagation Ant task fails, typically the failure is caused by one of these reasons:
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:
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.
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:
scope.properties
file, which you can edit. scope.properties
file.
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.
The steps shown in Figure 8-3 include the following:
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
. 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. 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. 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.
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.
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
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.
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.
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
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:
scope.properties
and a policy.properties
file. These files control how the two inventories are combined. 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.
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.