res-deploy

The res-deploy Ant task deploys a RuleApp archive to a running Rule Execution Server instance. The task uploads the archive through Hypertext Transfer Protocol (HTTP) or HTTP Over SSL (HTTPS).

When you deploy a RuleApp with a merging policy at the ruleset level, the RuleApp that already exists in the Rule Execution Server is updated with the deployed RuleApp (description, display name, properties). If you update this RuleApp by using the Rule Execution Server console, all modifications are lost at the next deployment that applies a merging policy at the ruleset level.

If the RuleApp archive does not contain any XOM, you can assign XOM resources (.jar or .zip files) to a ruleset path from the RuleApp archive by using the xompath nested element. Do not use the xompath nested element when an embedded managed Java™ XOM is in the RuleApp archive.

Note: When you use Ant to deploy a COBOL XOM to Rule Execution Server on z/OS® or to zRule Execution Server, add the COBOL XOM related libraries (./cobol-xom/*.jar) into the xompath element.

res-deploy element attributes

The following table describes the res-deploy element attributes and specifies whether they are mandatory or optional.

Table 1. res-deploy element attributes
Element attribute	Description	Mandatory/optional
authorizationToken	Supports token authentication by using OpenID Connect. If you set this attribute, it takes precedence over the credentialsfile, userid, and password attributes.	Optional
credentialsfile	A file that contains the `userid` and `password` values, encrypted the first time the attribute is used. If you set this attribute, do not use the userid and password attributes. A credentials file is a text file that sets two properties: username and password.	Optional
failonerror	The default is set to true. If it is set to false, a warning message is logged when an error occurs, but the build is not stopped.	Optional
file	The path of the RuleApp archive to deploy.	Mandatory
hostname	The host name of the server where the Rule Execution Server console is installed.	Mandatory
mergingpolicy	The server uses the merge policy to process the RuleApp archive. This attribute can take the following values: ADD_AT_END_MERGING_POLICY: The existing RuleApp is not modified and the version number of the new RuleApp is incremented to avoid a conflict. For example, if the RuleApp /MyRuleApp/1.0 already exists and you try to import a RuleApp archive that contains RuleApp/MyRuleApp/1.0, the existing RuleApp is not modified and the new RuleApp is added with version number 2.0. REPLACE_MERGING_POLICY: The existing RuleApp is replaced by the new RuleApp. With this policy, the versioningPolicy attribute is not used. ADD_AT_END_RULESET_MERGING_POLICY: The existing ruleset is not modified and the version number of the new ruleset is incremented to avoid a conflict. REPLACE_RULESET_MERGING_POLICY: The existing ruleset is replaced by the new ruleset. With this policy, the versioningPolicy attribute is not used.	Optional. The default value is ADD_AT_END_RULESET_MERGING_POLICY.
password	The password of the user who is allowed to log in to the Rule Execution Server console. If you set this attribute, do not use the credentialsfile attribute.	Optional
portnumber	The port number of the Rule Execution Server console.	Mandatory
secured	If you set this attribute to true, the task works through an HTTPS connection.	Optional The default value is false.
userid	The user name to log in the Rule Execution Server console. If you set this attribute, do not use the credentialsfile attribute.	Optional
versioningpolicy	The server uses the version policy to process the RuleApp archive. This attribute can take the following values: MAJOR_VERSION_POLICY MINOR_VERSION_POLICY	Optional. The default value is MINOR_VERSION_POLICY.
resourceVersioningPolicy	The server uses the version policy to process the resource in the RuleApp archive. This attribute can take the following values: MAJOR_VERSION_POLICY MINOR_VERSION_POLICY	Optional. The default value is MAJOR_VERSION_POLICY.
libraryVersioningPolicy	The server uses the version policy to process the library in the RuleApp archive. This attribute can take the following values: MAJOR_VERSION_POLICY MINOR_VERSION_POLICY	Optional. The default value is MINOR_VERSION_POLICY.
webapp	The context root of the Rule Execution Server console	Optional. The default value is res.

RuleApp deployment with no encryption

The following code sample shows how to deploy a RuleApp:

<res-deploy hostname="localhost" 
            portnumber="9080" 
            userid="res" 
            password="mypassword" 
            file="myruleapp.jar"/>

Encrypted credentials for RuleApp deployment

The following code sample shows how to run an encrypted res-deploy task by using the credentialsfile attribute:

<res-deploy hostname="localhost" 
            portnumber="9080" 
            credentialsfile="mypasswordfile" 
            file="myruleapp.jar"/>

The credentials file is a text file that sets the following values:

username=res
password=mypassword

The file must comply with the Java format for property files. See the Java documentation External link opens a new window or tab

. After the first execution of the res-deploy Ant task, the contents are encrypted. For example:

username={AES}6ee3l4NrmD3p8QTViSszow\=\=
password={AES}6ee3l4NrmD3p8QTViSszow\=\=

With encryption, the userid and password elements are never displayed in plain text in traces during RuleApp deployment.

Passing a trusted key

The following code sample shows how to pass a trusted key to the Ant task so that it authenticates with SSL on the application server:

java -Dant.home=c:\ant
     -Djavax.net.ssl.keyStore=stecert.jks
     -Djavax.net.ssl.trsutStore=cacerts.jks
     org.apache.tools.ant.Main res_deploy

xompath nested element attributes

When the RuleApp archive does not contain any XOM, you can use the xompath nested element to assign XOM resources (.jar or .zip files) to a ruleset path.

Restriction: The xompath nested element cannot be used when an embedded managed Java XOM is in the RuleApp archive.

The xompath nested element specifies a Path-like structure External link opens a new window or tab . All the files on this path are placed in the internal layer of the Rule Execution Server console as a .jar resource, in the same order as listed in the path. The xompath element supports the nested fileset element (see FileSet )

Table 2. xompath nested element attributes
Element attribute	Description	Mandatory/optional
jarMajorVersion	The server uses the version policy to process the .jar resources. If you set this attribute to true, the major version is incremented, if applicable. Otherwise, the minor version is incremented.	Optional The default value is false.
libMajorVersion	The server uses the version policy to process the library. If you set this attribute to true, the major version is incremented if necessary. Otherwise, the minor version is incremented.	Optional The default value is false.
libMergingPolicy	The server uses the merge policy to process the library. This attribute can take the following values: INCREMENT_MERGING_POLICY to increment the version during the deployment process REPLACE_LATEST_MERGING_POLICY to replace the last version during the deployment process	Optional
libName	The server uses this name to create a library. If you do not set this attribute, no library is created and the other library attributes, libMajorVersion and libMergingPolicy, are ignored.	Optional
property	If you set this attribute, it takes precedence over the rulesetpath attribute.	Optional
rulesetpath	The ruleset path in the RuleApp where the contained XOM resources must be used. Short paths are allowed.	Optional By default, all the rulesets in the RuleApp

Using xompath to assign resources to a ruleset path

The following code sample shows how to assign XOM resources to a ruleset through its path.

<target name="deployruleappwithxom">
    <res-deploy hostname="${hostname}" portnumber="${portnumber}" webapp="${webapp}" userid="${userid}" password="${password}" file="my-ruleapp.jar">
        <xompath rulesetpath="/MyRuleApp/MyRuleset">
          <fileset dir="${lib}">
              <include name="**/myxom.jar" />
          </fileset>
        </xompath>
        <xompath rulesetpath="/AnotherRuleApp/AnotherRuleset">
          <fileset dir="${otherlib}">
              <include name="**/otherxom.jar" />
          </fileset>
        </xompath>
    </res-deploy>
</target>