Start with Salesforce ant migration tool

Ant migration tool for Force.com is incredible tool which widens your development and deployment abilities.

First of all there are the list of the benefits which it brings to you

• deployment via command line in fully automated mode
• running unit tests during deployment to sandbox
• using Continuous Integration server like Jenkins

Let's see deeply. You need to install Apache Ant., after that you need to download migration tool from your Salesforce org by the following way: Setup → Develop → Tools, there is you can find a link to download. Next you just need to extract jar file into lib directory of ANT_HOME.

The next step is creation of build files and addition a connection information of your project to it. You can find the basic ant configuration here. This's GitHub repo where I collect Salesforce Ant Migration Tool configurations.

Here you can see the following structure

src/
build.properties
build.xml

This's basic structure for salesforce projects, where src directory was created by Eclipse and holds all metadata components in its own folders, and two files build.xml and build.properties which are generic for Ant.

build.properties is a file for a storing all configured properties, like username and password, urls, sandbox names, etc.

# build.properties
#
# Specify the login credentials for the desired Salesforce organization
sf.username = <Insert your Salesforce username here>
sf.password = <Insert your Salesforce password + Security Token here>
#sf.pkgName = <Insert comma separated package names to be retrieved>
#sf.zipFile = <Insert path of the zipfile to be retrieved>
#sf.metadataType = <Insert metadata type name for which listMetadata or bulkRetrieve operations are to be performed>

# Use ‘https://login.salesforce.com' for production or developer edition (the default if not specified).
# Use ‘https://test.salesforce.com for sandbox.
sf.serverurl = https://login.salesforce.com

sf.maxPoll = 20

build.xml is an Ant script which describes all possible build operations for your project. Below you can find the very basic ant script for Force.com.

<project name="Demo usage of Salesforce Ant Migration Tool" default="testDeploy" basedir="." xmlns:sf="antlib:com.salesforce">

<!– default properties –>
<property file="build.properties"/>
<property environment="env"/>
<property name="target" value="src" />

<target name="testDeploy">
    <!– Verify the abbility to upload the contents of the "src" package –>
    <sf:deploy username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="src" checkOnly="true" runAllTests="true"/>
</target>

<target name="deploy">
    <!– Upload the contents of the "src" directory and run all test –>
    <sf:deploy username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="scr" runAllTests="true">
    </sf:deploy>
</target>

<!– retriev metadata from org into local project folder src (by default), but it might be overridden in command line –>
<target name="retrieve" description="Retrieves metadata from ${sf.env} to ${target}" >
    <mkdir dir="${target}"/>
    <sf:retrieve username="${sf.username}${sf.env}" password="${sf.password}" serverurl="${sf.serverurl}" retrieveTarget="${target}" unpackaged="package.xml"/>
</target>

<!– Retrieve the information of all items of a particular metadata type –>
<target name="listMetadata">
    <sf:listMetadata username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}" metadataType="${sf.metadataType}"/>
</target>

<!– Retrieve the information on all supported metadata type –>
<target name="describeMetadata">
    <sf:describeMetadata username="${sf.username}" password="${sf.password}" serverurl="${sf.serverurl}"/>
</target>

</project>

Here are 5 targets:

• testDeploy
• deploy
• retrieve
• listMetadata
• describeMetadata

In the start you need just the first two.

testDeploy allows you to test deployment without committing any changes into the cloud environment. With this operation you can verify stability of all metadata components which are described in package.xml. For basic project it will take less than 1 min, what is faster than such operation via Eclipse in a few times.

~$ ant testDeploy

When you finished with testDeploy and have got no error messages, you can go ahead with deploy task which allows you to deploy all metadata components into you org with running all unit tests.

~$ ant deploy

These are the main tasks which would be used everyday, the 3 next tasks are more rarely used, the first one is retrieve which allows you to download the latest version of metadata from salesforce, by default it goes to src directorey, but if you need to redirect it to another folder you can use command line parameters

~$ ant -Dtarget=retrieveResults retrieve

This command will download metadata into folder retrieveResults which should be at same level with src dirrectory.

The other two target allow to list metadata in the org and describe it. It might be that you do not need to use them at all.