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

E14245-05
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

9 Propagation Ant Task Reference

This chapter describes the attributes, modifiers, and usage of the propagation Ant tasks. The Ant tasks are broken down into online and offline tasks. Online tasks interact directly with a WebLogic Portal application that is running on a server. Offline tasks interact with previously exported inventory files.

Note:

The propagation tools only work with inventories that were created using the same version of WebLogic Portal. For example, you cannot use an inventory generated with WebLogic Portal 10.0 with the propagation tools from a later version of WebLogic Portal.

Tip:

For a general overview of the Ant tasks, including use cases and examples, see Chapter 8, "Using the Propagation Ant Tasks."

This chapter includes the following sections:

9.1 Online Tasks

This section describes each of the online propagation Ant tasks. For an introduction to online tasks, see Section 8.4, "Overview of Online Tasks." The online tasks described in this section include:

9.1.1 OnlineCheckMutexTask

Verify that the propagation servlet is not currently in use by another process. The mutex is scoped to the application, and is cluster aware. This means that if anyone is using the servlet in a particular application on any node in the cluster, the mutex is enforced: another user cannot use the servlet for that application on another node.

Note:

This task requires you to be in the PortalSystemAdministrator role. See Section 7.2, "Security and Propagation" for more information.

Tip:

The propagation servlet executes propagation tasks on the server. This servlet performs operations on WebLogic Portal data, and therefore does not allow more than one thread of execution at a time. For more information on the propagation servlet, see Section 8.3.1, "Deploying the Propagation Servlet."

9.1.1.1 Attributes

  • allowHttp – (optional) If set to true, allows the propagation management servlet specified by servletURL to use HTTP. If set to false, allows the URL to use HTTPS. Default: false. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) Specifies a file to which the task writes concise log messages. For example: C:\mylogs\checkmutex.log. These log messages are generated on the server and returned by the propagation servlet. The messages can provide useful troubleshooting information if the propagation fails on the server. You must specify a file that does not currently exist. If you do not specify a log file, one is created automatically using the filename format: java.io.tmpdir/<antTaskName>_<date>.log.

  • password – (required) The user's password. The password can be specified either in plain text or 3DES encoded form.

  • retryTimes – (optional) An integer that sets the number of times to retry obtaining the mutex. Default = 1. A value of –1 indicates to retry indefinitely. After the specified number of retries, the task fails, unless the failOnError attribute is set to false.

  • servletURL – (required) The URL of the propagation management servlet. This URL must point to a specific managed node if in a cluster, not to a proxy. If the servlet is included in your EAR project, it is automatically deployed when you start your server. When it is deployed, you can access the servlet as follows:

    http://server:port/earProjectNamePropagation/inventorymanagement
    

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

  • username – (required) The name of a user with access to the destination server.

9.1.1.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The servlet mutex is available for use.

  • failure – The servlet mutex is locked by another thread. The task returns immediately without blocking.

9.1.1.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if another thread has the mutex. The script must wait for the other thread to complete. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.4.3, "Troubleshooting Online Tasks."

9.1.1.4 Usage

Example 9-1 checks to see if the propagation servlet is in use. The script retries 10 times. Example 9-2 uses an Ant conditional to test for success. If the task succeeds, a message is printed.

Example 9-1 OnlineCheckMutexTask Example

<target name="checkMutexDest"  description="checks to see if the mutex is available">
    <onlineCheckMutex
        servletURL="http://localhost:7001/myProjectPropagation/inventorymanagement" 
        username="weblogic"
        password="webl0gic"
        allowHttp="true"
        failOnError="false"
        retryTimes="10"
    />
</target>

Example 9-2 OnlineCheckMutexTask with Ant Conditional

<target name="checkMutexDest" description="checks to see if the mutex is available">
    <condition property="mutex_success">
        <onlineMutex
        servletURL="http://localhost:7001/myProjectPropagation/inventorymanagement" 
        username="weblogic"
        password="webl0gic"
        allowHttp="true"
        failOnError="false"
        retryTimes="10"
    />

    </condition>
    <antcall target="mutex_success" />
</target>

<target name="mutex_success" if="mutex_success">
    <echo message="The mutex is available." />
</target>

9.1.2 OnlineCommitTask

This task performs two operations:

  • Final Merge – If the differenceStrategy attribute is set to pessimistic, a redifferencing is performed to compute elections based on scope and/or policy settings. A new inventory file is created.

  • Commit – The task commits the final merged inventory to the destination server. Before you commit an inventory, you must upload it to the destination server using the OnlineUploadTask. The OnlineUploadTask places the inventory in a predetermined location, and the OnlineCommitTask always looks in that location. For this reason, you do not have to specify the name of the inventory file you are committing with this task. See also Section 9.1.6, "OnlineUploadTask."

    Note:

    This task requires you to be in the PortalSystemAdministrator role; however, it is recommended that you be in the Admin role to ensure that all resources can be read and/or modified. If you are not in the Admin role, this task will fail by default; however, you can set the AllowNonAdminUser modifier to override this default. See Section 7.2, "Security and Propagation" for more information.

    Note:

    This task will fail if the embedded LDAP data and security data in the database are out of sync. For example, if a role that exists in the database is deleted from the LDAP repository, this task will fail. You can force the task to continue using the modifier continueOnValidationError.

    Caution:

    This task modifies the target application's configuration. Any users with active sessions may experience unwanted behavior depending on the changes that are being committed. The risk to users is similar to the behavior they would see if an administrator made the same changes with the WebLogic Portal Administration Console.

9.1.2.1 Attributes

  • allowHttp – (optional) If set to true, allows the propagation management servlet specified by servletURL to use HTTP. If set to false, allows the URL to use HTTPS. Default: false. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) Specifies a file to which the task writes concise log messages. For example: C:\mylogs\commit.log. These log messages are generated on the server and returned by the propagation servlet. The messages can provide useful troubleshooting information if the propagation fails on the server. You must specify a file that does not currently exist. If you do not specify a log file, one is created automatically using the filename format: java.io.tmpdir/<antTaskName>_<date>.log.

  • password – (required) The user's password. The password can be specified either in plain text or 3DES encoded form.

  • servletURL – (required) The URL of the propagation management servlet. This URL must point to a specific managed node in a cluster, not to a proxy. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • username – (required) The username of a user with access to the destination server.

9.1.2.2 Modifiers

This section describes the <modifier> attributes available for this task. Each <modifier> attribute has a name and a value. See the Usage section for an example of using modifiers.

  • name = allowNonAdminUser

    If value = true, this modifier allows the task to continue if the user specified by the username attribute is not in the server's Admin role. To ensure that the propagation can read and modify all resources, it is recommended that the user be assigned the Admin role. Default: The user specified by the username attribute must be in the server's Admin role. If not, the task fails.

  • name = allowSecurityOutOfSync

    If value = true, this modifier allows the task to continue if the security information in the LDAP repository and the portal database are out of sync. Default: The task fails if the LDAP and portal database are out of sync.

  • name = allowMaintenanceModeDisabled

    If value = true, this modifier allows the task to continue if the server is not placed in maintenance mode. It is recommended that the server be placed in maintenance mode to avoid concurrent access to application resources. Default: The task fails if the server is not placed in maintenance mode.

  • name = cm_checkinComment

    Specifies a comment to use when new revisions of content are checked into a content management repository as a result of the propagation.

    value = A single line of text.

  • name = cm_checkoutPolicy

    Specifies what action to take when the task tries to update or delete a content item in a content management repository if that content item is already checked out.

    value = abort

    (default) Do not update or delete the content item and write a message to the log.

    value = revert

    Overrides the checked out content item, and adds or updates the content in the repository. This option reverts any changes made by the user who currently has the content item checked out and the changes in the change manifest are applied.

  • name = cm_nodeWorkflowPolicy

    When propagation is adding or updating content nodes there may be times when the workflow on the destination does not match the source. For example, the WLP content management system has a concept of workflow inheritance. If a node is inheriting its workflow from its parent it is possible that this parent is using a different workflow on the destination. After the node is added on the destination, its workflow would not match that on source. This modifier allows some control of these situations.

    When the node is being added to the destination:

    If the node did not inherit its workflow on the source, then propagation tries to set the node's workflow on the destination to that used on the source. If the node's workflow on source is inherited, then propagation does not try to set it, allowing it to inherit. But if the value that is inherited is null or does not match the value on source then this modifier's values have these meanings:

    • abort means do not perform the add.

    • retain means perform the update and accept the workflow inherited.

    When the node is being updated on the destination:

    If the node's workflow currently on the destination does not match the source, then:

    • abort means do not update the node.

    • retain means do the update and keep the workflow currently on the destination.

      Tip:

      Because WebLogic Portal does not propagate workflows, it is a best practice to ensure that the source and destination systems use exactly the same workflow. This practice ensures that nodes and types can be propagated with the least risk.

    value = retain

    (default) If the workflow name associated with a content node differs between the source and destination, retain the workflow on the destination.

    value = abort

    If the workflow name associated with a content node differs between the source and destination, do not propagate the node. Note that if any nodes on the source system depend on the aborted node, they cannot be propagated either.

  • name = cm_typeWorkflowPolicy

    When propagation is adding or updating content types there may be times when the workflow on the destination does not match the source. For example, the WLP content management system has a concept of workflow inheritance. If a type is inheriting its workflow from its parent it is possible that this parent is using a different workflow on the destination. After the type is added on the destination, its workflow would not match that on source. This modifier allows some control of these situations.

    When the type is being added to the destination:

    If the type did not inherit its workflow on the source, then propagation tries to set the type's workflow on the destination to that used on the source. If the type's workflow on source is inherited, then propagation does not try to set it, allowing it to inherit. But if the value that is inherited is null or does not match the value on source then this modifier's values have these meanings:

    • abort means do not perform the add.

    • retain means perform the update and accept the workflow inherited.

    When the type is being updated on the destination:

    If the type's workflow currently on the destination does not match the source, then:

    • abort means do not update the type.

    • retain means do the update and keep the workflow currently on the destination.

      Tip:

      Because WebLogic Portal does not propagate workflows, it is a best practice to ensure that the source and destination systems use exactly the same workflow. This practice ensures that nodes and types can be propagated with the least risk.

    value = retain

    (default) If the workflow name associated with a content type differs between the source and destination, retain the workflow on the destination.

    value = abort

    If the workflow name associated with a content type differs between the source and destination, do not propagate the type. Note that if any types on the source system depend on the aborted type, they cannot be propagated either.

  • name = differenceStrategy

    Specifies how the propagation management servlet obtains the list of differences to process before the final inventory is committed to the server.

    value = pessimistic

    (default) The propagation servlet computes the differences between the uploaded inventory and the application inventory. It then applies those differences according to the policy and scope settings provided with the uploaded inventory. Pessimistic causes differences to be re-computed in real time based on the current state of the destination. In other words, pessimistic is done to make sure that if the destination has changed since the final inventory was committed, then a current set of elections will be generated. See also Section 8.6.3, "Understanding a Scope Property File" and Section 8.7.1, "Understanding a Policies Property File."

    Note:

    Pessimistic differencing always takes longer than optimistic. This is because optimistic uses the elections in the change manifest of the combined inventory. Pessimistic ignores that change manifest and generates a new set of elections to make sure it is current.

    value = optimistic

    The propagation servlet looks for the changemanifest.xml file in the inventory. If the change manifest exists, it applies the specified elections from the manifest without recomputing the differences. With this option, the servlet does not honor scope or policy settings provided with the inventory. If this option is specified, but the changemanifest.xml file does not exist, the servlet defaults to pessimistic.

  • name = continueOnValidationError

    If value = true, this modifier forces the task to continue in the event of a validation error. A validation error can occur if the embedded LDAP repository and the security information in the database are out of sync. (default = false).

    Note:

    The continueOnValidationError modifier is deprecated. Use the allowSecurityOutOfSync modifier instead.

  • name = doAdds

    If value = true, if an asset exists in the source inventory, but not in the destination inventory, add it to the destination. This is a global policy setting. (default = true).

  • name = doUpdates

    If value = true, if an asset exists in the source inventory and in the destination inventory, update the destination with the artifact in the source inventory. This is a global policy setting. (default = true).

  • name = doDeletes

    If value = true, if an asset exists in the destination inventory, but not in the source inventory, delete it from the destination. This is a global policy setting. (default = true).

9.1.2.3 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – This task succeeds if the inventory is successfully committed.

  • failure – The inventory was not committed successfully. Check the log files for additional information.

9.1.2.4 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the inventory is not committed successfully. Check the log files for additional information. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.4.3, "Troubleshooting Online Tasks."

9.1.2.5 Usage

The following example commits the inventory file uploaded to the destination server with the OnlineUploadTask, which places the file in a standard location.

Example 9-3 OnlineCommitTask Example

<target name="commitOpt">
    <onlineCommit
        servletURL="http://localhost:7001/myProjectPropagation/inventorymanagement" 
        username="weblogic"
        password="webl0gic"
        allowHttp="true"
    >
        <modifier name="differenceStrategy" value="optimistic" />
        <modifier name="cm_checkinComment" value="My sample checkin comment." />
    </onlineCommit>
</target>

9.1.3 OnlineDownloadTask

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

Note:

This task requires you to be in the PortalSystemAdministrator role; however, it is recommended that you be in the Admin role to ensure that all resources can be read and/or modified. If you are not in the Admin role, this task will fail by default; however, you can set the AllowNonAdminUser modifier to override this default. See Section 7.2, "Security and Propagation" for more information.

Note:

This task will fail if the embedded LDAP data and security data in the database are out of sync. For example, if a role that exists in the database is deleted from the LDAP repository, this task will fail.

Note:

This task extracts the portal inventory and attempts to write it to a ZIP file. If the ZIP file created exceeds 4 GB, this task fails and a message is written to the server log and the verbose log. It is also written to the concise log that is returned to the client by the servlet. If this occurs, try scoping your inventory to limit the size of the resulting archive file. See Section 6.5, "Understanding Scope" for more information.

9.1.3.1 Attributes

  • allowHttp – (optional) If set to true, allows the propagation management servlet specified by servletURL to use HTTP. If set to false, allows the URL to use HTTPS. Default: false. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) Specifies a file to which the task writes concise log messages. For example: C:\mylogs\download.log. These log messages are generated on the server and returned by the propagation servlet. The messages can provide useful troubleshooting information if the propagation fails on the server. You must specify a file that does not currently exist. If you do not specify a log file, one is created automatically using the filename format: java.io.tmpdir/<antTaskName>_<date>.log.

  • outputInventoryFile – (required) The file in which to write the inventory file. If outputToServerFileSystem is false, the file is saved locally, the name can include a relative or absolute path, and it must not already exist. If outputToServerFileSystem is true, the file is written to the destination server system, you must supply an absolute path on the server system, and the file must not already exist.

  • outputToServerFileSystem – (optional) If true, the output file is written to the server file system. Use this attribute to avoid a lengthy HTTP download if the inventory file is large. Default: false.

  • password – (required) The user's password. The password can be specified either in plain text or 3DES encoded form.

  • scopeFile – (optional) The path name of the scope.properties file. If specified, this file must exist or the task will fail. See Section 8.6.1, "Scoping with Ant Tasks."

  • servletURL – (required) The URL of the propagation management servlet. This URL must point to a specific managed node in a cluster, not to a proxy. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • username – (required) The username of a user with access to the destination server.

9.1.3.2 Modifiers

This section describes the <modifier> attributes available for this task. Each <modifier> attribute has a name and a value. See the Usage section for the Section 9.1.2, "OnlineCommitTask" for an example of using modifiers.

  • name = allowNonAdminUser

    If value = true, this modifier allows the task to continue if the user specified by the username attribute is not in the server's Admin role. To ensure that the propagation can read and modify all resources, it is recommended that the user be assigned the Admin role. Default: The user specified by the username attribute must be in the server's Admin role. If not, the task fails.

  • name = allowSecurityOutOfSync

    If value = true, this modifier allows the task to continue if the security information in the LDAP repository and the portal database are out of sync. Default: The task fails if the LDAP and portal database are out of sync.

  • name = allowMaintenanceModeDisabled

    If value = true, this modifier allows the task to continue if the server is not placed in maintenance mode. It is recommended that the server be placed in maintenance mode to avoid concurrent access to application resources. Default: The task fails if the server is not placed in maintenance mode.

  • name = cm_exportPolicy

    This modifier controls what version of a content node in a managed repository is exported. If value = head, the head version of the content node is exported. If value = lastPublished, the last published version of the content node is exported. If lastPublished is specified and there is not a published version of the content node, then the node will not be exported. (default = head).

  • name = continueOnValidationError

    (Deprecated. Use allowSecurityOutOfSync instead.) If value = true, this modifier forces the task to continue in the event of a validation error. A validation error can occur if the embedded LDAP repository and the security information in the database are out of sync. (default = false).

9.1.3.3 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The inventory downloaded successfully.

  • failure – The download failed.

9.1.3.4 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the inventory is not downloaded successfully. Check the log files for more information. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.4.3, "Troubleshooting Online Tasks."

9.1.3.5 Usage

The following example downloads an inventory file called dest.zip.

Example 9-4 OnlineDownloadTask Example

<target name="downloadDest">
    <onlineDownload
    servletURL="http://localhost:7001/myProjectPropagation/inventorymanagement" 
    username="weblogic"
    password="webl0gic"
    allowHttp="true"
    outputInventoryFile="${portal.prop.home}/test/ant/dest.zip"
    />
</target>

9.1.4 OnlineMaintenanceModeTask

This task toggles the state of maintenance mode on the server.

In order to maintain data integrity during a propagation session, the applications on the source and destination servers must be placed into maintenance mode. Maintenance mode prevents administrators from making certain changes to the portal through the WebLogic Portal Administration Console. In maintenance mode, delegated administration and entitlement requests on specific resources are rejected. This means that certain API calls will fail when made by the administration console. In addition, calls to some of WLP APIs made in custom code will fail.

Maintenance mode takes effect for the entire enterprise application (not just a single web application) and it takes effect for all nodes in a cluster. After the export of the finalized inventory is complete, you can turn maintenance mode off to enable the applications on the server for modifications.

Note:

This task requires you to be in the PortalSystemAdministrator role. See Section 7.2, "Security and Propagation" for more information.

Tip:

You can also set Maintenance Mode in the WebLogic Portal Administration Console, select Configurations > Service Administration. For more information, refer to the online help.

9.1.4.1 Attributes

  • allowHttp – (optional) If set to true, allows the propagation management servlet specified by servletURL to use HTTP. If set to false, allows the URL to use HTTPS. Default: false. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • enable – (required) If set to true, turns maintenance mode on. To turn maintenance mode off, and thereby allow users to modify portal resources, set this value to false.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) Specifies a file to which the task writes concise log messages. For example: C:\mylogs\maintenancemode.log. These log messages are generated on the server and returned by the propagation servlet. The messages can provide useful troubleshooting information if the propagation fails on the server. You must specify a file that does not currently exist. If you do not specify a log file, one is created automatically using the filename format: java.io.tmpdir/<antTaskName>_<date>.log.

  • password – (required) The user's password. The password can be specified either in plain text or 3DES encoded form.

  • servletURL – (required) The URL of the propagation management servlet. This URL must point to a specific managed node if in a cluster, not to a proxy. For information on how to form this URL, see Section 8.3.1, "Deploying the Propagation Servlet." See also Section 8.4.2, "Using Online Tasks with HTTPS."

  • username – (required) The username of a user with access to the destination server.

9.1.4.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – Maintenance mode state was toggled successfully.

  • fails – Maintenance mode state could not be toggled. Check the maintenance mode state in the WebLogic Portal Administration Console.

9.1.4.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if maintenance mode could not be toggled. Check the Maintenance mode state in the WebLogic Portal Administration Console. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.4.3, "Troubleshooting Online Tasks."

9.1.4.4 Usage

Example 9-4 places the server into maintenance mode. Example 9-6 uses an Ant conditional to place the server in maintenance mode and print a message if the operation is successful.

Example 9-5 OnlineMaintenanceModeTask Example

<target name="lockDest" description="lock the server">
    <onlineMaintenanceMode
        servletURL="http://localhost:7001/propagation/inventorymanagement" 
        username="weblogic"
        password="webl0gic"
        allowHttp="true"
        enable="true"
    />
</target>

Example 9-6 Using OnlineMaintenanceModeTask with an Ant Conditional

<target name="lockDestC1" description="lock the server">
     <condition property="lock_success">
        <onlineMaintenanceMode
            servletURL="http://localhost:7001/propagation/inventorymanagement" 
            username="weblogic"
            password="webl0gic"
            allowHttp="true"
            enable="true"
        />
    </condition>
    <antcall target="lock_success" />
</target>
<target name="locksuccess" 
        if="lock_success">
            <echo message="Maintenance mode has been toggled."/>
</target>

9.1.5 OnlinePingTask

Tests if the propagation management servlet is running on the designated server. This task verifies that the propagation servlet can be contacted. For information on the propagation servlet, see Section 8.3.1, "Deploying the Propagation Servlet."

9.1.5.1 Attributes

  • allowHttp – (optional) If set to true, allows the propagation management servlet specified by servletURL to use HTTP. If set to false, allows the URL to use HTTPS. Default: false. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • password – (required) The user's password. The password can be specified either in plain text or 3DES encoded form.

  • servletURL – (required) The URL of the propagation management servlet. This URL must point to a specific managed node if in a cluster, not to a proxy. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • username – (required) The username of a user with access to the destination server.

9.1.5.2 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

9.1.5.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the servlet does not return a successful reply. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.4.3, "Troubleshooting Online Tasks."

9.1.5.4 Usage

Example 9-7 tests to see if the propagation servlet is running. Example 9-8 uses an Ant conditional to print a message if the task succeeds.

Example 9-7 OnlinePingTask Example

<target name="pingDest" description="ping the server">
    <onlinePing
        servletURL="http://localhost:7001/propagation/inventorymanagement" 
        username="weblogic"
        password="webl0gic"
        allowHttp="true"
    />
</target>

Example 9-8 OnlinePingTask Example with Ant Conditional

<target name="pingDest" description="ping the server">
    <condition property="ping_success">
        <onlinePing
            servletURL="http://localhost:7001/propagation/inventorymanagement" 
            username="weblogic"
            password="webl0gic"
            allowHttp="true"
        />

    </condition>
    <antcall target="ping_success" />
</target>

<target name="ping_success" if="ping_success">
     <echo message="The server is available." />
</target>

9.1.6 OnlineUploadTask

This task uploads an inventory file to a temporary location associated with a running WebLogic Portal application. You must execute this task before you execute the OnlineCommitTask. Only one inventory can be uploaded at a time.

This task overwrites an existing inventory file that exists in the upload location.

Note:

This task requires you to be in the PortalSystemAdministrator role. See Section 7.2, "Security and Propagation" for more information.

Note:

The user performing the propagation must have rights to the File Upload security policy of WebLogic Server or be in the Admin or Deployer role. See Section 7.2, "Security and Propagation" for more information.

Note:

This task only moves a file. It does not affect the configuration of the running application. This operation is safe to do even with active users on the system.

Note:

The propagation management servlet has a configuration setting to help mitigate "denial of service" attacks. The servlet is configured with a maximum size allowed for uploaded files (files uploaded over HTTP). By default, this is set to 1 MB. If any given file inside the inventory ZIP file is larger than this value, it will be rejected. The simplest way to work around this limit is to physically copy the inventory to the destination server, and then use the readFromServerFileSystem attribute of this task. For information on changing the servlet configuration to allow larger files, see Section 6.12, "Increasing the Default Upload File Size."

9.1.6.1 Attributes

  • allowHttp – (optional) If set to true, allows the propagation management servlet specified by servletURL to use HTTP. If set to false, allows the URL to use HTTPS. Default: false. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) Specifies a file to which the task writes concise log messages. For example: C:\mylogs\upload.log. These log messages are generated on the server and returned by the propagation servlet. The messages can provide useful troubleshooting information if the propagation fails on the server. You must specify a file that does not currently exist. If you do not specify a log file, one is created automatically using the filename format: java.io.tmpdir/<antTaskName>_<date>.log.

  • password – (required) The user's password. The password can be specified either in plain text or 3DES encoded form.

  • readFromServerFileSystem – (optional) If true, the inventory file is read from the destination server file system rather than from the source system. Use this attribute to eliminate the HTTP upload overhead for large files. Default: false.

  • servletURL – (required) The URL of the propagation management servlet. This URL must point to a specific managed node if in a cluster, not to a proxy. See also Section 8.4.2, "Using Online Tasks with HTTPS" and Section 8.3.1, "Deploying the Propagation Servlet."

  • sourceFile – (required) The file to read the inventory file (relative or absolute path), must exist. If readFromServerFileSystem is true, this file location is for the server file system.

  • username – (required) The username of a user with access to the destination server.

9.1.6.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The inventory uploaded successfully.

  • failure – The upload failed. Check the log files for more information.

9.1.6.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the upload fails. Check log files for more information. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.4.3, "Troubleshooting Online Tasks."

9.1.6.4 Usage

The following example uploads a file called combined.zip to the server.

Example 9-9 OnlineUploadTask Example

<target name="upload">
    <onlineUpload
        servletURL="http://localhost:7001/propagation/inventorymanagement" 
        username="weblogic"
        password="webl0gic"
        allowHttp="true"
        sourceFile="${portal.prop.home}/test/ant/combined.zip"
    />
</target>

9.2 Offline Tasks

This section describes each of the offline propagation Ant tasks. For an introduction to offline tasks, see Section 8.5, "Overview of Offline Tasks." The offline tasks described in this section include:

9.2.1 OfflineCheckManualElectionsTask

Tests for the presence of manual elections (changes). The task can check either an inventory file (containing a changemanifest.xml) or a changemanifest.xml specified directly. You can use this task to stop an automated propagation if any required manual changes are detected.

9.2.1.1 Attributes

Note:

You must specify either the changeManifestFile or the sourceFile attribute.

  • changeManifestFile – An XML file in which to write the differences found between the source and destination inventory files. The change manifest file must not already exist.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to true. Default: true.

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • sourceFile – A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.1.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – At least one manual election was found.

  • failure – No manual elections were found.

9.2.1.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if at least one manual election is detected. If failOnError is set to false, the task will not fail, but will report a message indicating a manual election was detected. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to true. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.1.4 Usage

The following example combines two inventories. Note that some of the attributes are taken from the Section 9.2.3, "OfflineDiffTask."

Example 9-10 OfflineCheckManualElectionsTask Example

<target name="checkManual" description="Checks for manual elections (changes)">
    <offlineCheckManualElections 
         changeManifestFile="${portal.prop.home}/test/ant/combine_cm.xml"" 
         logFile="${portal.prop.home}/test/ant/combine_log.txt"
         verboseLogFile="${portal.prop.home}/test/ant/combine_verboselog.txt"
    />
</target>

9.2.2 OfflineCombineTask

Combines two inventories and reports in a change manifest file the differences as a set of adds, updates, and deletes.

Note:

This task extends the Section 9.2.3, "OfflineDiffTask" task, so all attributes available for OfflineDiffTask can be used with this task too.

9.2.2.1 Attributes

  • combinedInventoryFile – (required) The ZIP file in which to write the combined inventory. The file must not already exist.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • sourceFile – (required) A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.2.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The inventory combination completed successfully and differences were found.

  • failure – Something failed during the operation or there were no differences found.

9.2.2.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if no differences were found between the two inventories. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.2.4 Usage

The following example combines two inventories. Note that some of the attributes are taken from the Section 9.2.3, "OfflineDiffTask."

Example 9-11 OfflineCombineTask Example

<target name="combine" description="Combine two inventories with logging">
    <offlineCombine 
         sourceFile="${portal.prop.home}/test/ant/src.zip" 
         destFile="${portal.prop.home}/test/ant/dest.zip"
         combinedInventoryFile="${portal.prop.home}/test/ant/combined.zip"
         changeManifestFile="${portal.prop.home}/test/ant/combine_cm.xml"
         logFile="${portal.prop.home}/test/ant/combine_log.txt"
         verboseLogFile="${portal.prop.home}/test/ant/combine_verboselog.txt"
    />
</target>

9.2.3 OfflineDiffTask

Compares two inventories and reports the differences in a change manifest file as a set of adds, updates, and deletes.

9.2.3.1 Attributes

  • changeManifestFile – (required) An XML file in which to write the differences found between the source and destination inventory files. The change manifest file must not already exist.

  • destFile – (required) A valid inventory file. This file contains the inventory of the destination portal application: the application you are propagating to.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • globalAddFlag – (optional) The flag to indicate the default policy for Adds unless overridden by the policies property file. Default: true. See also Section 8.7.1, "Understanding a Policies Property File."

  • globalDeleteFlag – (optional) The flag to indicate the default policy for Deletes unless overridden by the policies property file. Default: true. See also Section 8.7.1, "Understanding a Policies Property File."

  • globalUpdateFlag – (optional) The flag to indicate the default policy for Updates unless overidden by the policies property file. Default: true. See also Section 8.7.1, "Understanding a Policies Property File."

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • policiesFile – (optional) A file with a .properties extension that contains the policies to use when comparing or combining inventories. This file must exist if specified. See also Section 8.7, "Using Policies."

  • scopeFile – (optional) A file with a .properties extension that contains the scoping information to use when comparing or combining inventories. This file must exist if specified. See also Section 8.6, "Scoping an Inventory."

  • sourceFile – (required) A valid inventory file. This file contains the inventory of the source portal application: the application you are propagating from.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.3.2 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The diff operation completed successfully and one or more differences were found.

  • failure – The diff operation failed or no differences were found.

9.2.3.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if no differences are found. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.3.4 Usage

Example 9-12 writes the differences between two files to a change manifest file.

Example 9-12 OfflineDiffTask Example

<target name="diff" description="compare two inventories with logging">
    <offlineDiff 
        sourceFile="${portal.prop.home}/test/ant/src.zip" 
        destFile="${portal.prop.home}/test/ant/dest.zip"
        logFile="${portal.prop.home}/test/ant/diff_log.txt"
        verboseLogFile="${portal.prop.home}/test/ant/diff_verboselog.txt"
    />
</target>

9.2.4 OfflineElectionAlgebraTask

Allows for algebraic operations on two change manifest files.

  • Add Operation – Combines the two specified election lists. For any node that appears in both lists, the entry from election list 1 is used.

  • Subtract Operation – Removes any entry for a node in election list 1 if there exists an entry for that node in election list 2.

9.2.4.1 Attributes

  • electionList1File – (required) The XML file that contains change manifest file 1. Use the OfflineDiffTask to produce a change manifest file, or the OfflineExtractTask to extract a change manifest file from an existing inventory.

  • electionList2File – (required) The XML file that contains change manifest file 2.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • operation – (required) The operation to apply; valid values are: add or subtract.

  • outputFile – (required) The file in which to write the result elections.

9.2.4.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The algebraic operations completed successfully and one or more differences were found.

  • failure – The operation failed or no differences were found.

9.2.4.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the algebraic operation failed. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.4.4 Usage

Example 9-13 adds the contents of two change manifests. Example 9-14 subtracts the contents of two change manifests.

Example 9-13 OfflineElectionAlgebraTask Example: Add

<target name="electionsAdd" description="add the two election lists">
    <offlineAlgebra 
        electionList1File="${portal.prop.home}/test/ant/elections1.xml" 
        electionList2File="${portal.prop.home}/test/ant/elections2.xml" 
        operation="add"
        outputFile="${portal.prop.home}/test/ant/addedElections.xml"
    />
</target>

Example 9-14 OfflineElectionAlgebraTask Example: Subtract

<target name="electionsSubtract" description="subtract the two election lists">
/>
    <offlineAlgebra 
        electionList1File="${portal.prop.home}/test/ant/elections1.xml" 
        electionList2File="${portal.prop.home}/test/ant/elections2.xml" 
        operation="subtract"
        outputFile="${portal.prop.home}/test/ant/subtractedElections.xml"
    />

</target>

9.2.5 OfflineExtractTask

Extracts top level files from an inventory file. These files are stored in an inventory ZIP file at the top level of the file, and can include a change manifest file, export file, manual changes file, policy file, and scope file.

9.2.5.1 Attributes

  • changeManifestfile – (optional) The file in which to write the changemanifest.xml file from the inventory (if it exists). This XML file contains the change manifest file that describes all of the changes (adds, deletes, updates) made to the inventory. See also Section 9.2.3, "OfflineDiffTask."

  • exportFile – (optional) The file in which to write the export.properties file from the inventory. This file contains summary information about the inventory; including who exported it, when it was exported, how many nodes are in the export, and other information.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to failure, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • manualChangesFile – (optional) The file in which to write the manualchanges.xml file from the inventory (if it exists). This file is provided for convenience, and describes the manual changes that are required to propagate the inventory. See also Section 6.2.7, "Make Required Manual Changes."

  • policyFile – (optional) The file in which to write the policy.properties file from the inventory (if it exists). This file contains the policy rules that were used to produce the inventory. See also Section 8.7, "Using Policies."

  • sourceFile – (required) A valid inventory file.

  • scopeFile – (optional) The file in which to write the scope.properties file from the inventory (if it exists). This file contains the scoping rules that were used to produce the inventory. See also Section 8.6, "Scoping an Inventory."

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.5.2 Ant Conditional Support

This task does not support the Ant condition task.

9.2.5.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if any problems were encountered during the operation. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.5.4 Usage

The following example extracts specified files from an inventory file.

Example 9-15 OfflineExtractTask Example

<target name="extractCombined" description="gather resources from the combined inventory">
    <offlineExtract 
        sourceFile="${portal.prop.home}/test/ant/combined.zip" 
        exportFile="${portal.prop.home}/test/ant/extractCombined_export.properties"
        scopeFile="${portal.prop.home}/test/ant/extractCombined_scope.properties"
        policyFile="${portal.prop.home}/test/ant/extractCombined_policy.properties"
        changemanifestfile="${portal.prop.home}/test/ant/extractCombined_change.xml"
        logFile="${portal.prop.home}/test/ant/extractCombined_log.txt"
        verboseLogFile="${portal.prop.home}/test/ant/extractCombined_verboselog.txt"
    />
</target>

9.2.6 OfflineInsertTask

Inserts top level files into an inventory file. These files are stored in an inventory ZIP file at the top level of the file, and can include a change manifest file, export file, manual changes file, policy file, and scope file.

9.2.6.1 Attributes

  • changeManifestFile – (optional) The file to insert as the changemanifest.xml file from the inventory. This XML file contains the change manifest file that describes all of the changes (adds, deletes, updates) made to the inventory. See also Section 9.2.3, "OfflineDiffTask."

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • outputFile – (required) The ZIP file in which to write the new inventory. This file must not already exist

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • policyFile – (optional) The file to insert as the policy.properties file from the inventory. See also Section 8.7, "Using Policies."

  • scopeFile – (optional) The file to insert as the scope.properties file into the inventory. See also Section 8.6, "Scoping an Inventory."

  • sourceFile – (required) A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.6.2 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – If the insert succeeds.

  • failure – If the operation fails.

9.2.6.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the operation fails. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.6.4 Usage

The following example inserts specified files into an inventory.

Example 9-16 OfflineInsertTask Example

<target name="insertCombined" description="insert resources into combined inventory">
     <offlineInsert 
         sourceFile="${portal.prop.home}/test/ant/combined.zip" 
         policyFile="${portal.prop.home}/test/ant/extractCombined_policy.properties"
         changemanifestfile="${portal.prop.home}/test/ant/extractCombined_change.xml"
         outputFile="${portal.prop.home}/test/ant/newCombined.zip"
     />
</target>

9.2.7 OfflineListPoliciesTask

Exports the valid policies from an inventory file. These policies are written into a .properties text file. You can later edit this property file and use it as an input into other tasks, such as OfflineCombineTask. See also Section 8.7, "Using Policies."

9.2.7.1 Attributes

  • depth – (optional) Specifies the number of levels into the inventory tree to examine for policies. This attribute defaults to 3. This is a 0 based number, so a depth of 3 will examine the inventory tree 4 levels deep.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • globalAddFlag – (optional) The flag to indicate the default policy for Adds. Default: true. See also Section 8.7.1, "Understanding a Policies Property File."

  • globalDeleteFlag – (optional) The flag to indicate the default policy for Deletes. Default: true. See also Section 8.7.1, "Understanding a Policies Property File."

  • globalUpdateFlag – (optional) The flag to indicate the default policy for Updates. Default: true. See also Section 8.7.1, "Understanding a Policies Property File."

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • policyFile – (required) The file in which to write the valid policies. Give this file a .properties extension. This file must not already exist.

  • sourceFile – (required) A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.7.2 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The policy file is written successfully.

  • failure – The operation failed.

9.2.7.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the operation fails. The script can fail if there is a problem walking the inventory tree. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.7.4 Usage

The following example writes the policy file for the portal application.

Example 9-17 OfflineListPoliciesTask Example

<offlineListPolicies 
   sourceFile="${portal.prop.home}/test/ant/src.zip" 
   policyFile="${portal.prop.home}/test/ant/listPolicies_policies.properties"
   globalAddFlag="true"
   globalUpdateFlag="false"
   globalDeleteFlag="true"
   logFile="${portal.prop.home}/test/ant/listPolicies_log.txt"
   verboseLogFile="${portal.prop.home}/test/ant/listPolicies_verboselog.txt"
/>

9.2.8 OfflineListScopesTask

Exports the valid scoping information from an inventory file. Scopes are written into a .properties text file. You can later edit this property file and use it as an input into other tasks, such as OfflineCombineTask. See also Section 8.7, "Using Policies."

9.2.8.1 Attributes

  • depth – (optional) Specifies the number of levels into the inventory tree to examine for scopes. This attribute defaults to 3. This is a 0 based number, so a depth of 3 will examine the inventory tree 4 levels deep.

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • scopeFile – (required) The file in which to write the scope information. Give this file a .properties extension. This file must not already exist.

  • sourceFile – (required) A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.8.2 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The scope file was created successfully.

  • failure – The operation failed.

9.2.8.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if there was a problem traversing the inventory tree. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.8.4 Usage

The following example exports the scoped artifacts to a property file, using the default depth value of 3.

Example 9-18 OfflineListScopesTask Example

<target name="listScopes" description="lists the scopes found in the source inventory">
    <offlineListScopes 
        sourceFile="${portal.prop.home}/test/ant/src.zip" 
        scopeFile="${portal.prop.home}/test/ant/listScopes_scopes.properties"
        logFile="${portal.prop.home}/test/ant/listScopes_log.txt"
        verboseLogFile="${portal.prop.home}/test/ant/listScopes_verboselog.txt"
    />
</target>

9.2.9 OfflineSearchTask

Searches an inventory for node names that match the specified string. The search string is only matched if it occurs in the node name (the last term in the taxonomy).

For example, consider the following inventory:

1. Application

2. Application:PersonalizationService

3. Application:PersonalizationService:EventService:redEvent.evt

4. Application:PersonalizationService:EventService:coloredEvent.evt

5. Application:PersonalizationService:EventService:blueEvent.evt

If you search this inventory for the string red, the task returns nodes 3 and 4. If you search for PersonalizationService, the task returns just node 2.

9.2.9.1 Attributes

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • listFile – (required) The file in which to write the search results (the nodes that matched the search string). This file must not already exist.

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • searchString – (required) The task matches nodes that contain all or part of this string.

  • sourceFile – (required) A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.9.2 Ant Conditional Support

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

success – One or more matches are found.

failure – No matches are found or an error occurs.

9.2.9.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if no matches are found. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.9.4 Usage

Example 9-19 searches the specified inventory for the string global. Example 9-20 uses an Ant conditional to print a message if the search succeeds.

Example 9-19 OfflineSearchTask Example

<target name="search">
    <offlineSearch|
        searchString="global" 
        sourceFile="${portal.prop.home}/test/ant/src.zip" 
        listFile="${portal.prop.home}/test/ant/search.txt"
        logFile="${portal.prop.home}/test/ant/search_log.txt"
        verboseLogFile="${portal.prop.home}/test/ant/search_verboselog.txt"
    />
</target>

Example 9-20 OfflineSearchTask Example with Ant Conditional

<target name="searchC1" description="finds the nodes that contain the search string in
the name">
        <condition property="search_success">
             <offlineSearch 
                 searchString="esktop" 
                 sourceFile="${portal.prop.home}/test/ant/src.zip" 
             />
        </condition>

    <antcall target="search_success" />
</target>
<target name="search_success" if="search_success"><echo message="The search     succeeded." />
</target>

9.2.10 OfflineValidateTask

Verifies that the source ZIP file contains a valid portal application inventory. Use this task after moving or downloading an inventory to ensure that it was transferred successfully. This task ensures that the ZIP file's internal structure adheres to an exported inventory. It does not validate the XML of every node in the inventory tree.

9.2.10.1 Attributes

  • failOnError – (optional) Specifies the task behavior if the task fails. If set to true, the task ends in the event of an error. If set to false, the task does not terminate. If the task is used as part of an Ant conditional statement, failOnError does not apply; an error causes the conditional to evaluate to false. Default: true.

  • logFile – (optional) The name of a file. The task writes log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

  • sourceFile – (required) A valid inventory file.

  • verboseLogFile – (optional) The name of a file. The task writes verbose log messages to this file. If specified the file must not already exist. By default, the file is placed in the directory from which the task is run.

9.2.10.2 Ant Condition Property

This task supports the Ant condition task. The condition task's property is set if the Ant task succeeds.

  • success – The file is a valid inventory file.

  • failure – The file is not a valid inventory file.

9.2.10.3 On Failure

If the failOnError attribute is set to true (the default), the script terminates if the file is not a valid inventory file. If the task is used as part of an Ant conditional statement, failOnError does not apply. That is, if this attribute happens to be set to true, if an error occurs, the script does not terminate; rather, the Ant condition evaluates to false. See also Section 8.5.2, "Troubleshooting Offline Tasks."

9.2.10.4 Usage

The following example validates the inventory file called src.zip.

Example 9-21 OfflineValidateTask Example

<target name="validateSrc" description="valid inventory, with logging">
    <offlineValidate 
    sourceFile="${portal.prop.home}/test/ant/src.zip" 
    logFile="${portal.prop.home}/test/ant/validateSrc_log.txt"
    verboseLogFile="${portal.prop.home}/test/ant/validateSrc_verboselog.txt"
    />
</target>