Quick Guide to Using Apache Ant for Salesforce Deployments

Apache Ant is a Java library and command-line tool. Ant was originally used for building Java applications, but Salesforce.com supplies extra libraries to enable Ant to move metadata between a local directory and a Salesforce org. The Ant-Salesforce Libraries are known as the Force.com Migration Tool. There are many methods for migrating metadata (change sets, for example), but the Force.com Migration Tool is especially useful in these situations:

• Projects where you need to populate a test environment with large amounts of setup changes. Making these changes using a web interface could take a long time.
• Multistage release processes. Typically, a development process requires iterative building, testing, and staging before releasing to a production environment. Scripted retrieval and deployment of components can make this process much more efficient. Alternatives like change sets or the force.com IDE are not well suited for multistage release processes. This is especially true when the deployment has a large amount of metadata.
• Repetitive deployments using the same parameters. You can retrieve all the metadata in your organization, make changes, and deploy a subset of components. If you need to repeat this process, it\’s as simple as calling the same deployment target again.

The following steps are for installing ANT in a Windows OS environment:

STEP 1: Download, install, and extract ANT files

First you should download and install Apache ANT zip file from the salesforce.com. Click Your Name | Setup | Develop | Tools, then click Force.com Migration Tool. You should then unzip the files into a handy source directory that is easily accessible. I stored mine C:\\Program Files\\Ant

The Zip file contains the following:

• A Readme.html file that explains how to use the tools
• A Jar file containing the ant task: ant-salesforce.jar
• A sample folder containing:
  • A codepkg\\classes folder that contains SampleDeployClass.cls and SampleFailingTestClass.cls
  • A codepkg\\triggers folder that contains SampleAccountTrigger.trigger
  • A mypkg\\objects folder that contains the custom objects used in the examples
  • A removecodepkg folder that contains XML files for removing the examples from your organization
  • A sample build.properties file that you must edit, specifying your credentials, in order to run the sample ant tasks in build.xml
  • A sample build.xml file, that exercises the deploy and retrieveAPI calls

STEP 2: Set environment variables

You will have to set the path and then create a ANT_HOME and JAVA_HOME variable in your system advanced properties section. You can quickly access this by right clicking on My Computer>Properties>Advanced.

Once there, you should select the \”Environment Variables\” button at the bottom of the screen.

Set a new variable called \”ANT_HOME\” and set the path to the directory in which you installed ANT.

Set a new variable called \”JAVA_HOME\” and set the path to the directory in which your JDK is installed.

Modify the System Variable \”PATH\” to include the bin folder of your ANT installation.

Be careful to edit the path variable and never delete the other path from the variable value.

Java Home and Ant Home environment variables Screen.

STEP 3: Test your Installation

Open a new command prompt and type the word \”ant\” and you should receive the following message:

If the error message complains that ant does not exist, then your ant installation was not successful or environment variables does not proper set.

Step 4 Directory Structure of deploy root folder

• The first is build.XML, which handles which tasks you would like to perform.
• The second is build.PROPERTIES which manages the login credentials and org info for the orgs you wish to modify.
• The third is src which stores all of the resources that need to be deployed along with package.xml this will include templates, classes, objects, triggers, etc.
• In this example, the \”src\” folder is deploying root. It is more like eclipse “src” folder. Technically you can give folder name whatever you want but it should be same as in build.xml file.

Step 5: Deploy Code

cd (navigate) to directory where your code is stored. In my case this is “E:\\Salesforce ANT Test”. Please refer at step-4 screenshot for directory structure.

• Enter ant deployCode. This runs the deployAPI call, using the sample class and Account trigger provided with the Force.com Migration Tool. The ant deployCode calls the Ant target named deploy in the build.xml file.
• Sometime when your salesfoce org take time in deployment it is better to redirect ant log to a Log file. In my case I redirect to Log.txt in same directory. Syntax to redirect log to a text file is “ ant deployCode > Log.txt 2>&1”

Monitoring Deployments in Salesforce

• Things can go wrong on your end (e.g. Terminal quits, computer dies), don’t worry. As soon are you hit enter on a deployment, computation is happening in the cloud.
• You cannot stop a deployment once it is started from terminal. Control-C does nothing except stop Ant from reporting to your terminal window.
• To view a deployment status or terminate a deployment, you must log into Salesforce as a System Administrator.
• Once logged in navigate to Setup | Deploy | Deployment Status

• Here you can see Deployments in Progress and Completed Deployments Last 7 Days. In the Deployments in Progress you have the option of canceling, which will result as if there was a failure and nothing will be deployed. It is a good idea to have this window open while you are deploying, just in case you need to cancel for any reason.

Cheers!!!