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 you can get with it

  • 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. At start you need to install Apache Ant. After that you need to download migration tool from you Salesforce org by the following way: Setup → Develop → Tool there is you can find a link to download. After this you just need to extract jar file into lib directory of ANT_HOME. Ok, now you have an installed ant with Salesforce migration tool.

The next step is an adding build file and connection information to your project. You can find the basic ant configuration here it’s a github repo where I collect Salesforce Ant Migration Tool configurations.

Here you can see the following structure

It’s basic structure for salesforce projects, where src directory was created by Eclipse and holds all metadata components into their 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.

[code lang=”plain”]

# 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

[/code]

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.

[code lang=”xml”]

<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>

[/code]

Here are 5 targets:

  • testDeploy
  • deploy
  • retrieve
  • listMetadata
  • describeMetadata

For a start you need the first 2.

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

[code lang=”plain”] Your_project_location>ant testDeploy [/code]

As well as you have finished with testDeploy and had not got any 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.

[code lang=”plain”] Your_project_location>ant deploy [/code]

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

[code lang=”plain”] Your_project_location>ant -Dtarget=retrieveResults retrieve [/code]

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

Might be that 2 other target do not be needed at all. These one are for a listing and checking metadata into your org.

This is it for now.

[ant][force.com][migration tool][tools]