Ant tasks

DROPS comes with a set of Ant tasks designed to allow the creation and execution of import and deployment processes.

The JAR file containing the ANT task client API can be found in the directory where DROPS is installed: <DROPS Server installation directory>/clientAPI directory.

An exemplary Ant build file can also be found in this directory.

drops.import.filter

The drops.import.filter element is an embedded element that can be used with the drops.import.release task. If the *filterType attribute set to *MANUAL, then this element is used to specify the external version(s) to use for each import strategy run by that task.

The drops.import.filter element’s attributes
Attribute Description
*componentCode The code of the import strategy’s parent component.
*strategyCode The code of the import strategy to run.
*externalVersion The external version used by the import strategy.
Example
<drops.import.filter componentCode="SQL" strategyCode="svn" externalVersion="head" />

This task creates a reference to a DROPS Server and saves it in an ANT property. This property can be used later on by the drops.import.release task and the drops.deploy task to refer to a connection automatically.

The drops.instance task attributes
Attribute Description
*propertyName Create an ANT property to reference the connection to a DROPS Server that will include the URL, user and password defined below. Enter the name of the property to call later to refer to a connection automatically.
*url

The remote DROPS Server URL.

http://<server IP or network name>:<port>
*user A valid DROPS user.
*password The user's password.
Example
<drops.instance propertyName="drops.server" url="http://###.###.#.###:5254" user="James" password="Bond" />

This task creates and executes an import process instance for an application. The task supports the same range of options as the ones found in the New import process instance dialog, as described in the table below.

Reference

For more information about the parameters for an import process instance, refer to Create new import process instances.

The drops.import.release task's attributes
Attribute Description
*dropsServerProperty

The Ant tasks of the reference to the DROPS Server to use, defined by the Ant tasks.
*applicationCode The application that includes the artifacts to import.
*releaseNumber

The number of the release that will hold the imported artifacts. This value can be any release number that complies with the application's Release Number Template or *GEN.
releaseText The description of the release.
incrementPart

This attribute is required if the *releaseNumber is set to *GEN.

The part of the release number that will be increased to create the release. Can be MAJOR, MINOR, BUILD or REV.
*filterType

The import strategy to use to import the artifacts. Like in the DROPS Studio, three methods are available:

  • *NOFILTER: all import strategies are run using the release number as the external version number.
  • *MANUAL: import strategies listed using embedded drops.import.filter elements or listed in a local file are executed.
  • *FILE: import strategies listed in an external .properties file located on the DROPS Server are executed.
filterFilename

The absolute path on the DROPS Server of the .properties file that contains a list of import strategy codes and the external version number used to run each of them.

This attribute is only required if the *filterType is set to *FILE.
fromLocalFile

The absolute path of a local .properties file that contains a list of import strategy codes and the external version number used to run each of them.

This attribute is only used if the *filterType is set to *MANUAL.
resetRelease

If set to true and if the Release already exists, its content is cleared before artifacts are imported.

By default the value is false.
autoStart

If set to true, the import process instance created by this task is immediately executed. If set to false, it will have to be manually executed later.

By default the value is true.
waitForCompletion

If set to true and if autoStart is true as well, this task will block the execution until the import process is complete.

By default the value is true.
releaseNumberProperty

Create an ANT property to reference the release created when this task is run. Enter the name of the property to call.

This property can be used later as the *releaseNumber in the drops.deploy task to create and launch a deployment process for this release.
importResultProperty

The name of an ANT property that will be set with the result of the import process instance.

Import result:

0: succeeded
1: failed
2: unknown

Supported nested elements

  • drops.import.filter: if the task's *filterType attribute is set to *MANUAL, multiple elements can be used to describe the import strategies to be run and the external version numbers to use.
Example

The following example will create and execute a new import process for the DROPS_DEMO application. The release's number will be generated by incrementing its revision digit. Every component's import strategies will be run using the release Number as their external version number. The import process instance reference will be put in the drops.release property and the release number will be put in the drops.import.instance property.

This import process instance will be created and executed on the DROPS Server referenced by the drops.server property.

<drops.import.release
	dropsServerProperty="drops.server"
	applicationCode="DROPS_DEMO"
	releaseNumber="*GEN"
	releaseText="ANT task importation"
	incrementPart="REV"
	filterType="*NOFILTER"
	releaseNumberProperty="drops.release"
	instanceProperty="drops.import.instance" />
Example

Same as above, but this time the filterType attribute is set to *MANUAL. Consequently, two nested drops.import.filter elements are used to list the import strategies to be run: the SQL component’s svn strategy, and the IBMI component’s ARCAD strategy.

<drops.import.release
	dropsServerProperty="drops.server"
	applicationCode="DROPS_DEMO"
	releaseNumber="*GEN"
	releaseText="ANT task importation"
	incrementPart="REV"
	filterType="*MANUAL"
	releaseNumberProperty="drops.release"
	instanceProperty="drops.import.instance">
	<drops.import.filter componentCode="SQL" strategyCode="svn" externalVersion="head" />
	<drops.import.filter componentCode="IBMI" strategyCode="arcad" externalVersion="10.06.00" />
	</drops.import.release>
Example

Still the same as above, but the filterType attribute is set to *FILE. In this case, the filterFilename attribute is set to point to the location of a .properties file on the DROPS Server, that contains a list of import strategy codes and the external version number to use for each of them.

<drops.import.release
	dropsServerProperty="drops.server"
	applicationCode="DROPS_DEMO"
	releaseNumber="*GEN"
	releaseText="ANT task importation"
	incrementPart="REV"
	filterType="*FILE"
	filterFilename="/tools/release12547856.properties"
	releaseNumberProperty="drops.release"
	instanceProperty="drops.import.instance" />

This task creates and executes a deployment process instance for a given process and release number.

The release.deploy task's attributes
Attribute Description
*dropsServerProperty

The Ant tasks of the reference to the DROPS Server to use, defined by the Ant tasks.
*environmentCode The code of the environment holding the deployment process to run.
*processCode The code of the deployment process to run.
*releaseNumber

The release number of the release to deploy. Enter either a release number or the value of the releaseNumberProperty from the drops.import.release task.
transactionId The Transaction Id to use for this deployment process instance.
autoStart

If set to true, the deployment process instance created by this task is immediately executed. If set to false, it will have to be manually executed later on.

By default the value is true.
waitForCompletion

If set to true and if autoStart is true as well, this task will block the execution until the deployment process instance is done.

By default the value is true.
deploymentInstanceProperty

Create an ANT property to reference the deployment process instance created by this task.
deploymentResultProperty

Create an ANT property to reference the result of the execution of the deployment process instance created and executed by this task.

Deployment result:

0: succeeded
1: failed
2: unknown
5: succeeded with warnings
6: canceled
Example

Following the previous example, the previously imported release will be deployed using the process DEPLOY_DEMO from the UAT environment. The release number was retrieved from the releaseNumberProperty in the drops.import.release task and its value is now passed to the *releaseNumber attribute.

<drops.deploy
	dropsServerProperty="drops.server"
	environmentCode="UAT"
	processCode="DEPLOY_DEMO"
	releaseNumber="${drops.release}"
	deploymentResultProperty="drops.deployment.result" />

Classify your Server Credentials

As stated above, the drops.instance task element has a password attribute which is supposed to be confidential. ANT itself doesn't offer a way to hide this kind of information. However, because this information should classified and is used multiple times in an ANT script, it is advised to create an external .properties file with restricted permissions and allow the ANT script to load it using the <property> standard ANT tasks.

This method offers more flexibility and security over the credentials used to connect to the DROPS Server.

Example

A file named drops.credentials.properties is created under the /opt/tools/scripts directory. This file contains the following set of properties:

drops.server.url=http://###.###.#.###:5254
drops.port=5254
drops.user=James
drops.password=Bond

It is then possible to load these properties in an ANT script using the loadProperties ANT task:

<property file="/opt/tools/scripts/drops.credentials.properties" />

Then it is possible to use the properties retrieved from the credentials' file with the drops.instance task:

<drops.instance propertyName="drops.server" url="${drops.server.url}" login="${drops.user}" password="${drops.password}" />

Bellow is a sample ANT script that imports artifacts in a new release and deploys it on the go.

<project default="main">
	<taskdef resource="com/dropssoftware/client/ant/antlib.xml"/>
	 
	<!-- Required properties -->
	<property name="in.jenkins.build.number" value="" />
	<property name="in.drops.application" value="" />
	<property name="in.drops.environment" value="" />
	<property name="in.drops.process" value="" />
	<property name="in.drops.import.filter.file" value="" />
	<property file="${in.drops.server.properties}" />
	 
	<!-- Optional properties -->
	<property name="in.drops.increment.part" value="REV" />
	<property name="in.drops.release.number" value="*GEN" />
	 
	<!-- Global properties -->
	<property name="drops.server.url" value="http://${drops.server}:${drops.port}"/>
	<target name="main" depends="connect, importation, deployment" />
	<target name="connect">
		<drops.instance propertyName="drops.server" url="${drops.server.url}" login="${drops.user}" password="${drops.password}" />
	</target>
	<target name="importation">
		<drops.import.release
		dropsServerProperty="drops.server"
		applicationCode="${in.drops.application}"
		releaseNumber="${in.drops.release.number}"
		releaseText="Automatic import from Jenkins Build #${in.jenkins.build.number}"
		incrementPart="${in.drops.increment.part}"
		filterType="*MANUAL"
		fromLocalFile="${in.drops.import.filter.file}"
		releaseNumberProperty="drops.release"/>
		<echo>Release ${drops.release} imported successfully.</echo>
	</target>
	<target name="deployment" if="drops.release">
		<drops.deploy
		dropsServerProperty="drops.server"
		environmentCode="${in.drops.environment}"
		processCode="${in.drops.process}"
		releaseNumber="${drops.release}"/>
	<echo>Deployment of release ${drops.release} of application ${in.drops.application} on environment ${in.drops.environment} is done.</echo>
	</target>
</project>